flights

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: the default free model, the BYO Anthropic key with direct billing to the user, and the per-model response structure. This transparency about cost and external API usage is valuable and not contradicted by annotations.

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

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

The description is three sentences with no fluff: the first sentence states the core action, the second covers model defaults and the API key requirement, and the third gives the return format and use cases. It is front-loaded and every word earns its place.

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

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

Despite lacking an output schema, the description explicitly enumerates the per-model return fields (score, confidence, signals, raw_response) and the combined view. It also covers model selection, cost, and use cases. A minor gap is the undefined nature of 'signals', but the overall mental model is complete.

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

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

Schema description coverage is 100%, with clear descriptions for entity, models, _apiKey, and context. The description's mention of the default Workers AI model and the need for _apiKey to probe Anthropic essentially restates what the schema already says, adding no new parameter-level insight. 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 opens with a specific verb and resource: 'Probe one or more LLMs' and 'score visibility (0-100) per model'. This clearly distinguishes it from sibling tools like ask_pipeworx or compare_entities, which are general Q&A or comparison tools. It also states the output format immediately.

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 usage context by listing 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives like scan_competitor_ai_presence or say when not to use this tool, but the use cases are specific enough to guide selection.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: the tool routes to sub-tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is dense and front-loaded, with the preference directive, domain list, usage triggers, and examples all serving a clear purpose. It loses a point for slight redundancy: 'even if web search could also answer it' appears twice, and the long domain list could be trimmed without losing meaning.

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 natural-language router with no output schema, the description covers the key operational details: what inputs to accept, what kinds of questions to route, and what the answer will look like (structured with citations). It is incomplete only in not explaining behavior when no matching tool exists or how to choose among sibling ask_pipeworx variants.

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 the schema already explains the question parameter and its five aliases. The description adds example queries but no additional parameter constraints, formats, or edge-case guidance, so it does not meaningfully extend 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 answers factual questions by routing them to one of 5,798 tools across verified sources and returning structured data with citations. It lists concrete domains and example queries, so a model can immediately tell what the tool does. However, it does not differentiate from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded.

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 triggers ('what is', 'look up', 'find', 'get the latest', 'current') and says to prefer it over web search, with 'START HERE for most questions'. It does not, however, state when to use ask_pipeworx_grounded, ask_pipeworx_beta, deep_research, or other siblings, so the when-not guidance is incomplete.

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 this as read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: it is an experimental edge, candidates may be enabled live, it currently matches the stable router, and it falls back to nothing because it is a full working router.

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

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

The description is somewhat verbose, with status details like the retirement date, but every sentence adds meaningful information about beta status, current equivalence, and usage. It is front-loaded with the core identity and use guidance before the more peripheral experimental details.

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

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

The description is strong for a router tool with rich annotations and no output schema: it tells the agent the tool is a full working router, matches ask_pipeworx, and has no fallback. It relies on 'same response shape' rather than specifying the response format, but the sibling reference and clear usage guidance cover most of what an agent 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?

Schema description coverage is high (100%), so the schema carries the parameter weight. The description adds no direct parameter detail beyond saying the router takes the same arguments as ask_pipeworx, which directs the agent to the sibling tool but does not explicitly clarify the question/alias relationship.

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

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

The description states a specific purpose: it is a beta version of the ask_pipeworx universal router, with the same tools, arguments, and response shape. It clearly distinguishes itself from the sibling ask_pipeworx by noting candidate routing improvements and experimental status.

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 the agent when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state (no candidate active, so it matches ask_pipeworx exactly), which removes ambiguity about choosing between the beta and stable versions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the core mechanism: routing across 5,798 tools, fetching data, extracting only from tool results, and returning either an evidence-backed answer or an explicit refusal with specific reason codes. It also reveals the cost behavior (one extra LLM call). This is rich behavioral disclosure well beyond the structured 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?

Four dense, purpose-driven sentences: purpose, mechanism, return/refusal contract, usage guidance, and cost tradeoff. Every sentence earns its place and the key differentiator ('grounded', 'ONLY what the tool result contains') is front-loaded. There is no redundant restatement of schema or annotations.

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

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

With no output schema, the description fully compensates by specifying the success return shape and the refusal object with all refusal_reason values. It also covers operational context (routing scale, extra LLM call) and decision context (high-stakes vs casual). Nothing needed to select and invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents the question parameter and aliases. The description does not add parameter-level detail beyond contextual use-case examples (financial verdicts, legal claims), which are more about usage than semantics. The description neither improves nor harms parameter understanding.

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

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

The description states a specific, distinctive purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clarifies it performs grounded extraction using only tool results, and explicitly differentiates it from ask_pipeworx by name. The agent can immediately tell this is a grounded/question-answering tool, not a general lookup.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' It also names the alternative and gives the condition to prefer it: 'prefer ask_pipeworx for casual lookups.' The tradeoff (extra LLM call) is clearly linked to the selection decision.

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 communicate readOnly, openWorld, idempotent, and non-destructive behavior, but the description goes far beyond by disclosing resolver contracts (market_match_score, alternatives[], suggestions[]), safety short-circuiting (status:'low_confidence_match'), handling of closed/dead markets, wide-spread illiquidity flags, and resolution-rule cancellation policies. This is rich behavioral context that no annotation could convey, and it does not contradict any annotation.

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 extremely well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Every sentence appears to add substantive detail relevant to successful use, making the length appropriate for a complex tool, though it could arguably be trimmed for raw conciseness.

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

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

With no output schema, the description must fully explain return values, and it does: result.market, result.analysis, result.evidence, resolver contract fields, parent_event, news fallback fields, and status conditions. It also covers resolution-rule risk and parameter tradeoffs. For a tool of this complexity with no structured output schema, the description is exceptionally complete.

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

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

The input schema covers all three parameters (market, depth, include_raw) with descriptions, so baseline is 3. The description adds context on fan-out behavior and typical usage examples, but does not materially expand parameter semantics beyond the schema—e.g., it never directly explains the 'depth' enum values or the 'include_raw' size tradeoffs beyond what the schema already states.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool resolves, classifies, fans out, and returns an evidence packet plus market-vs-model comparison, distinguishing it from sibling tools focused on edges, arbitrage, or general search.

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 text explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', which gives clear context for when to invoke it. However, it does not explicitly name alternatives or state when NOT to use it, though the purpose itself separates it from related Polymarket 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 detail beyond the annotations: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and the return format (paired data + citation URIs). It also discloses that results are sorted so 'largest' reads off the top, which helps the agent set expectations.

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 the one-sentence ideal, but every clause adds functional information (triggers, data sources, sorting, citations). It is front-loaded with the most critical trigger examples and preference instruction, then dives into specifics. The density justifies the length, though it could be slightly tightened.

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

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

With no output schema, the description compensates by describing the return format (paired data + citation URIs) and sorting behavior. It also covers data source specifics and fiscal year handling. Combined with read-only and idempotent annotations, the agent has a complete picture of what to expect and how to use the tool.

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

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

While the schema already describes both parameters (coverage 100%), the description enriches their semantics by explaining what each 'type' actually pulls (e.g., company -> 10-K revenue, drug -> FAERS counts) and gives examples for 'values'. This goes beyond the bare enum and array descriptions, adding meaningful context for parameter selection.

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

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

The description opens with concrete trigger phrases and a specific verb+resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes itself from sibling tools like entity_profile or resolve_entity by emphasizing the multi-entity comparison scope and the efficiency gain over 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?

Explicit guidance is given: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also enumerates the exact user expressions that should invoke this tool ('X vs Y', 'which is bigger', 'rank these companies') and scopes the tool to 2–5 entities, which tells the agent when to choose it over alternatives.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context beyond them: account and paid-tier requirements, 15-90s latency expectations, the findings-packet shape, the never-invented gaps[] guarantee, contradictions[] on standard/thorough, semantic excerpting rather than head-truncation, and citation_uri resolvability. All disclosed behaviors are consistent with the annotations — nothing contradicts them.

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 most important facts are front-loaded (account requirement, non-open-web scope, when to use vs ask_pipeworx), but the description is long and contains a garbled/corrupted fragment mid-way — '(One request per call — ONE pass through. Next: come back for multi-part or anything that needs TWO passes: ...' — that breaks coherence. Depth semantics are also re-explained in prose, partially duplicating the schema's depth description, which adds length without new 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?

For a complex tool with no output schema, the description carries the return-format burden fully: findings packet fields, gaps[], contradictions[], hop field, citation URIs, latency ranges, auth/tier prerequisites, and the not-open-web-search scoping. The garbled fragment is a recoverable blemish — the depth behavior it gestures at is fully covered both in the schema and in the surrounding prose — so no essential coverage gap remains.

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 the baseline is 3; the description adds meaning beyond the schema by coupling 'thorough' to a paid plan (absent from the schema) and by mapping each depth value to observable behavior (single hop vs gap-recovery vs iterative lead-chasing) that complements the schema's own enum descriptions. It doesn't fully transform the parameters, but it clearly adds value.

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

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

States a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call', and explicitly contrasts with 'this is NOT open-web search.' It distinguishes cleanly from sibling ask_pipeworx by scope (broad/multi-part research vs single lookup) and from the many other data-lookup siblings like get_flights_in_area or 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?

Gives explicit condition-based routing: 'If you are not signed in, use ask_pipeworx instead — it works on every tier' and 'For a single lookup use ask_pipeworx.' Affirmative guidance is concrete too: 'Best for broad/multi-part questions over structured data' with two worked example phrasings. An agent knows exactly when to pick this tool and when to pick the alternative.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds behavioral detail beyond that: it specifies the return format ('names, descriptions, and full input schemas with curated examples') and the efficiency property ('no second schema lookup needed'). It doesn't mention rate limits or auth, but for a read-only discovery tool this is sufficient given the annotation coverage.

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

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

The description is three sentences, front-loaded with the core action ('Find tools...'). The domain list is long but serves as useful query examples and occupies less than half the text. The 'Call this FIRST' advice is strategic and earns its place. No redundant or filler content.

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 burden of explaining return values, and it does so explicitly ('top-N most relevant tools with names, descriptions, and full input schemas'). It also covers the tool's scope with the domain list and mentions the 'ready to call directly' benefit. Annotations cover safety, so the description is complete for a discovery tool.

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

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

The input schema has 100% coverage with descriptions for every parameter, including aliases (q, task, search, description) and limit. The description's phrase 'describing the data or task' aligns with the query parameter, and 'top-N' clarifies limit, but it doesn't extend significantly beyond what the schema already states. 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's function: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings by noting it returns the tool set itself ('Call this FIRST... to see the option set, not just one answer'), which differentiates it from tools that perform the actual tasks.

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

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

It provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when not to use it ('not just one answer') but doesn't name an alternative tool directly, slightly reducing the clarity of exclusion.

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?

Even with readOnlyHint/openWorldHint/idempotentHint already present, the description adds substantial behavioral detail: it fans out across specified sources, soft-fails on the USPTO endpoint, treats empty sections as genuine 'no data', and returns resolved:false with a notes line for private companies. There is no contradiction with annotations.

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

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

The description is long, but the material is dense and almost every sentence carries distinct information about sources, return fields, failure modes, or invocation rules. It is front-loaded with purpose and preference. A short list of redundant example phrasings at the start is the only real 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 there is no output schema, the description carries the full responsibility for explaining return shape, and it does so thoroughly: it lists cik/company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and the sources_used/sources_failed fields. It also covers edge cases like private companies and software sunset behavior. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is already strong. The description adds value by explicitly stating that type='company' and type='ticker' are interchangeable, that value may be a ticker, zero-padded CIK, or company name, and that names resolve via SEC EDGAR. This clarifies the enum semantics beyond the schema alone.

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

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

The description opens with concrete trigger phrasings and then states a precise job: 'full cross-source profile of a US public company in ONE parallel call.' It also names the exact resource class (US public company) and the output concept, distinguishing it from single-pack SEC/XBRL/news lookups. An agent can tell what this tool is for immediately.

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 clarifies input forms and the private-company fallback behavior. It does not explicitly contrast itself with sibling tools like deep_research or compare_entities, but the 'US public company holistic profile' scope is a clear selection criterion.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to repeat them. It adds no behavioral context beyond the annotations—no mention of irreversibility, failure behavior, or key-not-found handling. It only adds usage guidance, which belongs to a different dimension. 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?

Two sentences, action is front-loaded, no filler. Every phrase earns its place: the delete operation, the 'by key' qualifier, and the usage trigger conditions plus sibling tools.

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

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

The tool is simple (one required parameter, no output schema, no nested objects). The description covers what the tool does, when to use it, and how it relates to siblings. Annotations cover safety implications. Nothing essential is missing 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%, and the single parameter 'key' is described as 'Memory key to delete.' The description reinforces 'by key' but adds no new semantic detail beyond the schema. Baseline 3 applies because the schema carries the full load.

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 begins with a specific verb and resource: 'Delete a previously stored memory by key.' This is unambiguous and distinguishes it from sibling tools like remember and recall, which store and retrieve memories respectively.

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

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

Explicit conditions are given: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also names complementary tools: 'Pair with remember and recall,' which signals when to use those alternatives and this tool's role in the workflow.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context: it fetches the page, extracts specific elements, and returns a single text blob in standard llms.txt markdown. This goes beyond the annotations without contradicting them.

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

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

The description is compact: three sentences that lead with the core purpose, then a brief process summary, then specific use cases. Every sentence adds value, with 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?

For a two-parameter tool with no output schema, the description is complete: it explains the tool's purpose, process, output format, and likely use cases. The annotations cover safety, and the description covers behavior and output, leaving no significant gaps for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% parameter coverage with clear descriptions for both 'url' and 'max_links'. The description adds context about the URL (foreshadows fetching and extracting), but doesn't elaborate on 'max_links' beyond what the schema already states. Baseline is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's verb ('Generate'), the specific resource ('llms.txt file for any URL'), and the concrete actions (fetch page, extract title/description/key links, emit markdown). This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on analysis rather than file generation.

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

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

The description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving context on when to use the tool. It doesn't explicitly mention alternatives or when not to use it, but the guidance is clear and actionable.

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

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

Annotations already cover safety (readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false). The description adds meaningful behavioral context: 'No key required' discloses authentication needs, and 'plus its LIVE position if it is currently transmitting' clarifies conditional data availability. This goes beyond annotations without contradicting them.

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

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

The description is compact and front-loaded: identification, return contents, auth requirement, usage examples, and alternative tool in just five short sentences. Every sentence earns its place with 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?

For a simple one-parameter tool with an output schema, the description fully covers purpose, parameter semantics, usage examples, authentication, and alternatives. The presence of an output schema means return values are already defined, so no additional explanation is needed. Complete and self-contained.

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% for the single parameter, with format, case-insensitivity, and examples already given. The description reiterates the ICAO24 hex format but adds little beyond the schema, so the baseline of 3 is appropriate.

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

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

The description is highly specific: 'Look up ONE aircraft by ICAO24 transponder hex' clearly identifies the verb, resource, and scope. It distinguishes itself from siblings like get_flights_in_area by emphasizing single-aircraft lookup, and explicitly mentions a sibling alternative. It also enumerates return contents (registry details, live position), leaving no ambiguity.

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 for "what is aircraft <hex>", "who operates <hex>", "where is <hex> now"'. It also provides a clear exclusion: 'If you only have a flight number/callsign, use get_flight_route instead.' This is exactly the kind of direct, actionable usage guidance expected.

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 and idempotent, but the description adds critical behavioral context: 'no key required', 'nearest first', the specific return fields, and the significant caveat that historical windows require OpenSky credentials and self-hosting ('OpenSky is unreachable from cloud egress'). This goes well beyond the annotations.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, the second provides usage and output details, and the third resolves ambiguity about live vs. scheduled data. The historical caveat is parenthetical to avoid distraction. Every sentence earns its place.

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

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

With 5 parameters, a detailed schema, rich annotations, and an output schema, the description is complete. It covers use cases, limitations, and technical requirements, leaving no significant gaps for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning by giving ICAO examples, clarifying that results are 'nearest first', and explaining the begin/end historical limitation in context. It reinforces and extends the schema descriptions rather than merely repeating them.

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: 'Aircraft currently ARRIVING at an airport — live ADS-B' and specifies the output (inbound traffic with callsign, altitude, etc.). It distinguishes arrivals from siblings like get_departures and get_flights_in_area by focusing on inbound traffic to a specific airport.

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

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

Explicit usage guidance is provided with example queries ('Use for "what is landing at <airport> right now"') and a clear disclaimer ('This is a live picture, not a scheduled timetable'). It also warns about historical window limitations. However, it does not explicitly name alternative tools, so it falls just 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?

Beyond the readOnly/idempotent annotations, it discloses that no key is required for live data, explains the historical window credential/self-hosting constraint, and notes OpenSky unreachability from cloud egress—all useful behavioral traits not present in annotations.

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

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

The description is compact and front-loaded, starting with the core action, then giving examples, use cases, and a caveat. Every sentence earns its place with 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 an output schema and fully described parameters, the description covers the main use case, live-vs-historical distinction, and limitations. It provides enough context for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, with detailed descriptions for every parameter (including credential requirements for begin/end and defaults). The description largely restates these, adding only contextual flavor like 'climbing out of the field' but no new parameter-level semantics.

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

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

The description clearly states the tool returns aircraft currently departing an airport, listing specific fields like callsign, registration, and altitude. It explicitly uses 'DEPARTING' and mentions 'outbound traffic', distinguishing it from get_arrivals.

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

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

It provides explicit use cases ("what just took off from <airport>", "outbound traffic from <airport>") and warns it is a live picture, not a scheduled timetable. However, it does not explicitly name the alternative for arrivals (get_arrivals) or 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 already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds 'No key required' (authentication context) and 'scheduled ROUTE' (clarifying it is schedule-based, not real-time), which go beyond the annotations. It does not cover error handling or rate limits, but with annotations this is adequate.

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

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

Four purposeful sentences: purpose, authentication note, concrete use cases, and sibling differentiation. No redundancy or filler; the key verb and resource appear first.

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 lookup with no output schema, the description adequately covers input, output (airline, route, airports, codes, coordinates), use cases, and access requirements. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the parameter description already defines callsign as ICAO or IATA form with examples. The tool description repeats the same examples ('UAL1', 'BAW117') without adding additional semantic 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 the specific verb 'Resolve' and identifies the resource (flight callsign) and output (airline and scheduled route with airports/codes/coordinates). It explicitly differentiates from sibling get_flights_in_area, making the tool's role clear.

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

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

The description provides explicit use cases: 'where does flight X fly from/to', 'what route is <callsign>', and 'which airline is <callsign>'. It also names get_flights_in_area as the complementary tool for overhead callsigns, giving a clear alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context beyond annotations: data is 'LIVE ADS-B', 'no key required', and it lists the exact return fields including emergency code. This provides useful operational context not present in the annotations, though it doesn't mention potential delays or limits beyond the schema's limit parameter.

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?

Every sentence earns its place: purpose, data source, return fields, use cases, and sibling alternatives. It is slightly long but front-loaded and free of filler, making it efficient and well-structured.

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

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

Given the tool complexity (5 params), rich annotations, and presence of an output schema, the description covers all necessary context: what it does, when to use it, what it returns, and how it differs from siblings. No critical information is missing.

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

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

Schema coverage is 100%, so the description does not need to document parameters. The description only mentions 'bounding box' conceptually and does not add extra meaning beyond the schema's already-complete property descriptions. 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 uses a specific verb ('Find'), names the resource ('aircraft currently airborne in a geographic area'), and specifies the method ('by bounding box'). It also distinguishes itself from siblings by naming get_aircraft and get_flight_route as alternatives for different use cases.

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

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

Provides explicit use cases ('what planes are over <place> right now', 'aircraft near <airport>', 'is anything squawking 7700 near X') and explicitly names alternatives ('For one known aircraft use get_aircraft; for what route a callsign flies use get_flight_route'). This gives clear when-to-use and when-not-to-use guidance.

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

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

With annotations declaring readOnlyHint, idempotentHint, and openWorldHint, the description adds value by specifying it returns only the caller's subscriptions and that include_inactive defaults to false. It also lists the exact fields returned, which compensates for the lack of an output schema. No contradiction with annotations.

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

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

The description is only two sentences: the first states the action and output fields, the second gives usage guidance. All content is relevant and there is no fluff, earning a top score.

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-only list tool with one optional parameter and rich annotations, the description is complete. It covers purpose, returned fields, and usage context; the lack of an output schema is mitigated by listing fields inline. Some might want pagination info, but the low complexity makes this acceptable.

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 fully documents include_inactive with its default value (100% coverage), so the baseline is 3. The description does not elaborate on the parameter, but it does hint that cancelled subscriptions might be relevant when finding an id to cancel. Since the schema is explicit, no additional semantic burden is placed on the description.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and enumerates the returned fields (id, type, params, created_at, etc.). This distinguishes it from mutation siblings like subscribe/unsubscribe and other monitoring 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 explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' giving clear when-to-use context. It doesn't explicitly name alternatives, but it aligns with subscribe/unsubscribe siblings, making the usage intention unambiguous.

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

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

With all annotation hints false, the description carries the transparency burden. It discloses rate limits (5 per day), the claim_token return flow, and that feedback doesn't count against quota. It also advises not to paste end-user prompts, implying privacy care. Missing explicit statement about data retention or human reading, but 'team reads digests daily' covers that.

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 typical, but every sentence earns its place—purpose, usage exclusions, token flow, rate limits, and a 'not sure?' helper. It's front-loaded with the primary action and contains no fluff, though it could be tightened.

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 key return behavior (claim_token on filing without account, status on later lookup). It covers the main feedback flow, exclusions, and limits. It doesn't describe response structure when filing with an account, but that's a minor 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 covers 100% of parameters, but the description adds meaningful operational detail: it explains the meaning of type values, the claim_token usage as a subsequent read call, and message guidelines to reference Pipeworx tools. This goes beyond the schema's field descriptions.

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

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

The description opens with a specific verb ('Tell') and resource ('the Pipeworx team'), then enumerates the exact categories of feedback (bug, feature/data_gap, praise). It clearly distinguishes this tool from sibling tools by focusing on reporting issues with Pipeworx tools themselves rather than querying or researching.

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 (bug, feature gap, praise) and when-not-to-use, including a strong exclusion for feedback about other MCP servers. It also explains the claim_token follow-up mechanism, making it clear this is for Pipeworx-specific feedback only.

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 meaningful behavioral context beyond the annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' It discloses data origin, caching behavior, and privacy characteristics. Combined with the readOnly/idempotent hints, this gives a solid picture 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 moderately sized but well-structured, starting with a clear one-line summary followed by a bulleted list of use cases and a final note on data source/caching. Each sentence adds value, though the 'Useful for' list could be slightly tightened. Overall, it is efficient 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's simplicity (one optional parameter, no output schema), the description is complete: it states what is returned, the windows available, use cases, data derivation, privacy, and caching. No other behavioral or contextual aspects appear missing. The annotations and schema complement the description well.

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

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

The single parameter `window` is fully documented in the schema with enum values and descriptions. The tool description repeats the window options ('24h, 7d, or 30d') but does not add new semantic details beyond what the schema already provides. With 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('Returns') and names the resource ('Pipeworx'), distinguishing it from siblings like discover_tools by focusing on what other agents are calling. The opening sentence immediately conveys the core purpose.

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 three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. This is clear context for when to use the tool, though it does not mention specific alternatives or exclusions. While it lacks a direct comparison to siblings, the use cases make the intended application clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: the partition_check logic (sum of YES prices ≈1, deviations >3pp emit a signal), the FILL CHECK that prices against live CLOB depth and warns when realizable_edge_pp ≤ 0, the SEMANTIC ANCHOR threshold (≥0.30 Jaccard similarity), and the PARTITION FILTER behavior (placeholders >20% return null). These details tell the agent exactly what happens under various conditions, far exceeding the annotation baseline.

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?

Although the description is long, it is densely packed and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it scannable. Every sentence adds necessary operational detail for a complex tool. The opening sentence immediately conveys the core action, and the response format is included, saving the agent from guessing return values. No filler or redundancy.

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

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

The tool has no output schema, so the description compensates by specifying the response structure: opportunities[] with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context), partition_check fields, and fill check details. It covers all modes, edge cases, and the meaning of null results. Given the tool's complexity, this description is remarkably complete, leaving no major ambiguity about invocation or 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 input schema already describes both parameters (event and topic) with examples. The description adds substantial meaning by explaining how each parameter changes the tool's behavior (single-event vs cross-event scanning), what kind of values to pass (event slugs like 'fed-decision-may-2026' or topic questions like 'Strait of Hormuz'), and what outputs to expect in each mode. This goes well beyond the schema's field descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and provides concrete examples, making it obvious what the tool does and how it differs from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also gives examples of slugs and seed questions, and even mentions an alternative tool: 'For custom sizing use polymarket_fill_risk.' This exceeds basic guidance by providing clear selection criteria and 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?

Beyond the generic annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses substantial behavior: caching at KV level for 1h keyed on knobs, model-family methodology, slippage handling, placeholder-slug filtering, rare-by-design longshot gates, the unreliable Fed-signal note, and diagnostics for empty segments. This is rich, honest behavioral disclosure 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 long but information-dense, with a clear front-loaded purpose and logical sectioning via ALL-CAPS labels. Some content overlaps with the schema's parameter descriptions, but each sentence adds operational context; minor tightening or bullet formatting could improve scannability.

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

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

With no output schema, the description compensates fully by documenting the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields, and why segments may be empty. It also covers knob interactions and caching, making the tool's behavior and response shape unambiguous for an agent.

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

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

The schema already covers all 9 parameters (100% coverage), but the description adds meaningful semantics beyond the schema: edge is 'NET of slippage', slippage_pp is subtracted 'before ranking and Kelly sizing', max_spread_pp and min_liquidity are explicitly 'Tradeable-edge filters', and min_partition_leg_kelly clarifies why parent-level kelly is zero and how the per-leg filter works. This helps the agent choose parameters 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 opens with a specific verb-resource-outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today') and describes the output segments, making it clearly distinct from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 clear context for when to use the tool ('agents discover opportunities without paging hundreds of markets') and explains tradeable-edge knobs that shape invocation. However, it does not explicitly name alternatives or state when NOT to use it (e.g., for tracking edges over time or cross-platform arbitrage), so it falls just short of the highest bar.

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

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

The description goes well beyond the annotations (readOnlyHint, idempotentHint) by detailing response structure, the meaning of expired opportunities, snapshot date gaps, the 60-day TTL limitation, and the computation of decay numbers from daily closes. This rich context is highly valuable and does not contradict any annotations.

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

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

The description is well-structured with Args, RESPONSE, and LIMITS sections. Every sentence contributes meaningful information, and the purpose is front-loaded. Despite its length, it is densely packed and not wasteful.

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

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

With no output schema, the description fully explains the return values (tracked[], expired[], snapshot_dates[]) including field details. It also covers limitations, prerequisites, and edge cases (snapshot gaps, TTL), making the tool's behavior and expectations clear for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'snapshot family' concept for the window parameter and how days affect the response (e.g., snapshot_dates shows actual data availability). It reinforces defaults and clamps, which helps but is somewhat redundant with 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 specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a concrete question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from sibling tools like polymarket_edges by focusing on the time dimension and decay analysis, not just current edge values.

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

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

The description gives strong contextual guidance: it explains that a fresh edge and a 3-week-old edge are different trades, implying when historical persistence matters. It does not explicitly name alternatives or state when-not to use the tool, but the context is clear enough for an agent to infer appropriate use cases.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: how size_usd is interpreted differently for buys vs sells and single vs basket mode, the list of outputs (slippage_pp, capture_ratio, thin_legs, forced_directional_risk), and the risk of partial fills. No contradiction with annotations; it enriches them.

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?

Long but well-organized with ALL-CAPS section markers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) that make it scannable. Every sentence carries technical meaning—no filler, no repetition of schema/annotations—and the structured format earns the length.

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

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

The tool is complex with two modes and no output schema, yet the description thoroughly covers inputs, outputs, edge cases (thin_legs, forced_directional_risk), and failure modes. It even explains the significance of partial fills and stranded positions, giving the agent a complete mental model of the tool's behavior and limitations.

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 all 4 parameters with detailed descriptions (100% coverage). The description further clarifies semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market, and 'settlement notional S (shares per leg)' in basket mode. It also explains the auto-side default for baskets, adding value beyond the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the two modes (single-market vs basket) and explicitly connects itself to sibling tools (polymarket_arbitrage, polymarket_edges) by positioning as a pre-trade validation step.

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

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

Provides explicit when-to-use criteria: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable, partial basket fills convert arb into unhedged directional position), effectively guiding agent decision-making.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses rich behavioral caveats: compatibility_codes can be non-empty even with matched_pairs>0, temporal_alignment null means 'could not be computed' not 'aligned', Kalshi fees are not modeled so all spreads are gross, unclassified legs are never paired, and pairing_unverified is always set because matching is keyword-based. This goes far beyond the annotation hints.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, CODES). It front-loads the core concept before diving into details. Some redundancy exists — temporal_alignment_unknown is explained both in the code list and again for the temporal_alignment field — but given the tool's complexity and lack of an output schema, the density is largely 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?

With no output schema and three optional parameters, this description carries the full burden of explaining behavior, and it does so thoroughly: return shape (leg prices, top_spreads_pp, skipped counters), safety flags, temporal alignment semantics, fee caveat, and edge cases like unclassified legs. An agent has everything needed to call the tool correctly and interpret its results.

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

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

The input schema already documents all three parameters with 100% coverage, setting a baseline of 3. The description adds meaning by explaining the mode interaction: topic auto-fetches the matching event on each venue, while explicit ticker/slug override the mapped side, and both modes run the identical token-overlap matcher. This clarifies relationships the schema alone doesn't convey.

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 sentence defines the exact scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes it from Polymarket-only siblings like polymarket_arbitrage and polymarket_edges. The description goes further to explain the delta signal and the two modes, leaving no ambiguity about what the tool computes.

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

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

The description clearly explains when to use each mode: topic shortcuts for 10 pre-mapped macro topics versus explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility warnings today. However, it never names sibling alternatives or states 'use X instead when...', so it stops short of explicit when-not guidance.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the list-all-keys behavior when the key is omitted. This adds useful 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 three sentences with no fluff, front-loading the primary action and then providing usage guidance and scoping information. Every sentence earns its place.

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

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

For a simple read-only tool with one optional parameter, the description fully covers purpose, usage, scoping, and companion tools. No output schema exists, but return behavior is implied and adequate 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 a clear parameter description, but the tool description adds further meaning by explaining that omitting the key lists all keys and providing example key contents (ticker, address, research notes). This goes beyond the schema's basic definition.

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

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

The description clearly states the tool retrieves a previously saved value or lists all saved keys when the key argument is omitted. It uses a specific verb (retrieve/list) and resource (memory), and distinguishes itself from siblings like remember 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?

It explicitly says to use this tool for looking up stored context without re-deriving it, and pairs it with remember (to save) and forget (to delete). This makes the usage context and alternatives 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?

There is a direct annotation contradiction: annotations mark readOnlyHint:true, but the description explicitly describes mutation via 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This is a state-changing operation, conflicting with read-only semantics. The idempotentHint is also questionable when mark_read is used repeatedly. Such contradictions confuse the agent about side effects.

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

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

The description is three sentences, each earning its place: the first states the core function, the second details return contents, and the third covers filtering, mark_read, polling, and an alternative endpoint. It is compact, front-loaded, and contains 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?

The description covers the return payload (source, citation_uri, raw event payload), filtering options, mark_read side effects, polling suitability, and an external endpoint. No output schema exists, so the description carries the burden of explaining return values, which it does. However, the contradiction with readOnlyHint leaves a completeness gap regarding side effects, though the description itself is fairly comprehensive.

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 five parameters. The description adds value by providing an example for type ('sec_8k'), clarifying since as 'ISO timestamp,' and explaining the broader effect of mark_read: 'so the next call only shows newer ones.' It also mentions the return payload fields, though those are not parameters. This goes beyond the schema's basic descriptions.

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

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

The description starts with 'Pull fired events from your subscription feed,' which clearly identifies the verb (pull) and resource (subscription feed/alerts). It also distinguishes itself from sibling tools like list_subscriptions and subscribe by focusing on retrieving fired events.

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

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

The description provides clear context for use: filtering by type/since, setting mark_read for polling new events, and noting that 'Polls work fine.' It also suggests an alternative for scripts/dashboards via 'GET registry.pipeworx.io/alerts.json.' It does not explicitly exclude other use cases or name sibling alternatives, but the guidance is clear.

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

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

The description discloses significant behavior beyond the readOnly/openWorld/idempotent annotations: fan-out to SEC EDGAR, GDELT/GNews fallback logic, USPTO soft-fail due to PatentsView API sunset, and the exact return shape (changes[] grouped by source, total_changes, citation URIs). This contextualizes what happens during execution without contradicting 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?

Despite its length, the description is tightly packed with indispensable information. It front-loads the user intent, then explains the multi-source fan-out, parameter format, return structure, and closes with an explicit alternative tool. No sentence is wasted; the density is justified by the tool's complexity.

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

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

With no output schema, the description compensates by detailing the return value structure (changes[], total_changes, citation URIs). It also covers edge cases (API sunset, fallback conditions) and the only supported entity type. Combined with the rich annotations and full parameter schema, the description provides a complete operational picture.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for 'since' ('7d', '30d', '3m', '1y') and noting typical monitoring values ('Use "30d" or "1m"'), which the schema does not include. It also reinforces the 'type' enum and 'value' format, making the parameter guidance more actionable.

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

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

The description clearly defines the tool as a 'change feed' for a company over a time window, with concrete query examples like 'What's new with X' and 'updates on Acme'. It explicitly distinguishes from the sibling tool entity_profile by stating when to use that instead, making the purpose unambiguous.

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

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

It provides explicit usage context with natural language examples and a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also describes when fallback sources are used (e.g., GDELT preferred, GNews on rate-limit/5xx), which helps an agent decide when to invoke this tool.

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

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

The description adds valuable behavioral context beyond the annotations: key-value pair scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. This is meaningful supplementary information that helps the agent understand side effects and scope.

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

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

The description is concise and front-loaded with core purpose. Every sentence adds value, from primary action to usage context to persistence caveats to tool pairings. No superfluous wording.

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 storage tool with 2 well-documented parameters and no output schema, this description covers all essential dimensions: what it does, when to use it, how it behaves (scope, persistence), and how it relates to sibling tools. It 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?

The schema already provides descriptions for both key and value (100% coverage). The description enriches this with context about the kind of content to store ('resolved ticker, target address, user preference'), which helps the agent choose appropriate keys and values in practice.

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

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

The description clearly states the tool saves data for reuse later, using a specific verb ('Save') and resource ('data'). It distinguishes itself from sibling tools by explicitly mentioning recall and forget as complementary 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 when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples like 'a resolved ticker, a target address, a user preference, a research subject.' It also names alternatives (recall, forget) and their purposes.

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

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

Beyond the readOnly/idempotent annotations, the description discloses substantial behavior: it cascades through multiple endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns figi_candidates when ambiguous, and explicitly reports unresolved identifiers under an `unresolved` field. This gives the agent a realistic model of the tool's execution even without an output schema.

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

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

The description is front-loaded with examples and the key trigger, but it becomes a dense wall of text with nested parentheticals (e.g., the long FIGI explanation, the ISIN-to-LEI aside). Most sentences carry useful information, but the structure could be tightened with bullets or shorter clauses without losing meaning.

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 two-parameter tool with no output schema, the description covers the essential runtime behaviors: accepted inputs, source identifiers, ambiguity handling, resilience to external-service failures, and unresolved-result reporting. An agent has enough context to invoke it correctly and interpret unexpected outcomes.

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 significant value beyond the schema: concrete ticker/CIK/ISIN examples for company, brand/generic examples for drug, and critical guidance on passing only the entity name (not the full noun phrase) for bond lookups. This materially prevents misparameterization.

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

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

The description clearly defines the tool as resolving user-spoken names to canonical identifiers and enumerates concrete supported types (company, drug) with their output identifiers. This distinguishes it from likely siblings like entity_profile and compare_entities: it is explicitly positioned as the tool to use when you have a name but need an ID.

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 an explicit trigger: "Use FIRST whenever you have a name but need an ID," reinforced with example phrasings. It also covers edge cases like ambiguous instrument names and graceful degradation, but it does not explicitly name sibling tools to avoid or state when NOT to use this tool, so it stops short of full 5-level 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 readOnly/idempotent/non-destructive, and the description adds behavioral detail: it probes with ai_visibility_check, ranks by score, and returns score, confidence, and signal density. This goes beyond the annotation hints, though it does not mention potential multi-call cost or rate limits.

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

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

Three sentences: front-loaded purpose, process, use case, and return summary. Every sentence carries distinct information with no filler or redundancy.

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

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

Despite having no output schema, the description explains the return format (ranked list with score, confidence, signal density). It also gives a concrete use case and example, making it easy to understand when to invoke this tool. No critical gaps for a comparative read-only operation.

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

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

The input schema already provides comprehensive descriptions for all parameters (100% coverage), including the first-entity-as-subject rule and model options. The tool description adds minimal new parameter meaning, so it appropriately relies on 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 function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (AI visibility) and the action (compare/probe/rank), and distinguishes itself from sibling ai_visibility_check by focusing on multiple entities and ranking them.

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

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

Provides a specific use case ('competitive AI-marketing audits') and an illustrative example query. It implicitly differentiates from ai_visibility_check by saying it 'probes each entity...' and returns a ranked list, but does not explicitly state when not to use it or name alternative tools for single-entity checks.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable non-obvious behavioral details: bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully via a 'sources_failed' field, and the specific output fields are listed. 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?

Every sentence earns its place: main purpose, use cases, return summary fields, ecosystem scope, and failure behavior. The description is front-loaded with the core purpose and remains information-dense without wasting words, given the tool's complexity.

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

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

Despite having no output schema, the description enumerates the summary block fields, per-advisory detail, links, recent alternative versions, and handles edge cases like timeouts and partial failures. It gives an agent sufficient context to know exactly what will happen and when to use the tool.

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

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

Schema coverage is 100% with both parameters fully described ('package' and 'version'). The description does not add parameter-specific semantics beyond what the schema already states, e.g., 'Defaults to the latest published version' is already in 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 identifies a composite npm package evaluation tool with a specific verb ('scan') and resource ('dependency'), explicitly framing it as a 'should I add this npm package' check. It distinguishes itself from any sibling by naming its two data sources (deps.dev and bundlephobia) and the consolidated return.

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

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

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clearly scopes to the npm ecosystem and directs non-npm ecosystems to 'deps.dev:version directly', which serves as an alternative tool route.

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?

Even with readOnlyHint/idempotentHint annotations, the description adds significant behavioral detail: the exact embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), and a 200K-character cap with truncation-and-flag behavior. This transparency helps an agent predict output quality and avoid size-related surprises.

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?

At roughly 120 words, the description is dense yet every sentence earns its place. It front-loads the core purpose, then covers usage, pairing, and technical constraints in a logical flow, with no redundant or filler language.

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

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

The tool has no output schema, so the description correctly carries the burden of describing the return format — 'top-N passages with character offsets and similarity scores.' Combined with the truncation cap and pairing guidance, the description gives an agent all the contextual information needed to choose and invoke the tool effectively.

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

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

The input schema already provides 100% coverage with detailed descriptions for text, query, and limit (including max length, default, and query examples). While the description reinforces roles via phrases like 'text you already pulled' and 'natural-language query,' it introduces no new parameter-level semantics beyond what the schema already contains. It meets the baseline but does not elevate 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 opens with the precise verb-resource phrase 'Semantic search INSIDE a fetched record,' immediately distinguishing it from broader search tools. Concrete examples (SEC 10-K, article, long tool result) further anchor its niche, and the contrast with 'too big to cram into the prompt' makes the purpose unmistakable.

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

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

It explicitly states the triggering condition — 'Use when the record is too big to cram into the prompt' — and highlights the context-saving benefit. It also names ask_pipeworx_grounded as a complementary sibling and describes how to chain it, which is actionable guidance beyond a generic list of alternatives.

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

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

The description goes far beyond annotations by disclosing concrete operational behaviors: authentication requirements, phone verification for SMS, a 10/day cap, webhook auto-disable after 10 consecutive failures, and a one-time HMAC signing secret. These details are absent from the annotations and are critical for understanding side effects and constraints.

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?

Despite the length, every sentence earns its place: purpose, return value, OAuth requirement, type examples, delivery options with specifics. The information is dense but organized, front-loaded with the primary purpose, and uses colons and parentheticals to pack examples without redundancy. It is appropriately sized for a tool being described to an AI agent.

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

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

With no output schema, the description explicitly covers the return value ('Returns the new subscription id'). It addresses prerequisites, all supported subscription types with parameter examples, delivery channels, and constraints like phone verification and SMS limits. The nested parameter structure is well-explained, making the tool fully usable from the description alone.

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

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

The input schema already provides 100% coverage with detailed descriptions for each parameter, setting a baseline of 3. The description adds tangible value with concrete examples like items:['5.02'] = officer change for sec_8k, topic:'fed' for polymarket_edge, and series_id:'UNRATE' for fred_series, which clarify semantics beyond generic schema text. However, since the schema already covers most type-specific details, the marginal gain is not enough for a 5.

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 and resource: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly distinguishes it from sibling tools like list_subscriptions (viewing existing) and unsubscribe (removing), and the mention of 'Returns the new subscription id' completes the core purpose.

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

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

It explicitly states prerequisites and exclusions: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also provides guidance on when to pull instead of subscribe by mentioning 'feed (always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json)', and enumerates supported types with examples, helping the agent select the right subscription type.

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

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

The description adds behavioral context beyond annotations by explaining that the output is derived from the 'live catalog of thousands of tools' and that results include tool+argument shapes. It also describes the effect of passing vs. omitting the topic parameter. Annotations already declare read-only/idempotent, but the description enriches the understanding of response content.

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 moderately long but front-loaded with common user queries, then pivots to purpose, output, and usage. While every sentence adds value, the list of categories is somewhat expansive and could be trimmed. Overall, it's efficient and well-structured for an onboarding 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?

The description is complete for an onboarding tool with no output schema: it fully explains the return format (category-bucketed example questions), parameter behavior, and when to use it. Rich annotations cover safety and mutability. A small gap is the lack of limits or pagination details, but this is unlikely to be critical for an entry-point tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only reiterates what the schema states (omit for full spread, pass topic to focus) without adding new semantic detail. The examples in the description ('finance', 'pharma', 'betting') mirror the schema's enum-like values and do not enhance meaning beyond 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 with a specific verb+resource: it is the onboarding entry point that returns category-bucketed example questions with the exact tool+argument shape. It distinguishes itself from sibling tools by explicitly positioning itself as the 'getting started' entry point, not a general search or 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?

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This directly tells the agent when to invoke this tool over alternatives and names the meta-tools it helps learn, making the decision 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 mark readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details beyond annotations: ownership enforcement and that the row is deactivated (not deleted), which is a non-obvious side effect. No contradiction with annotations.

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

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

Three sentences, each serving a purpose: action, ownership, and deactivation consequence with a pointer to recent_alerts. Front-loaded with the core verb, 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 single-parameter tool with strong annotations, the description covers action, ownership, and side effects. It omits explicit error behavior (e.g., what happens if the id is not found or not owned), but this is a minor gap given the tool's 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?

The schema fully documents the 'id' parameter as 'Subscription id (uuid) returned by subscribe' (100% coverage). The description adds the constraint that it must be your own subscription, giving extra semantic 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 opens with 'Cancel a subscription by id' — a specific verb and resource. It clearly distinguishes from siblings like subscribe (create) and list_subscriptions (list) by focusing on cancellation, and adds the ownership constraint for further clarity.

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

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

The description implies the tool is for canceling your own subscriptions and clarifies that historical events remain available via recent_alerts, which guides when to use it. However, it does not explicitly contrast with subscribe or list_subscriptions, relying instead on context from sibling 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 (readOnly, idempotent) are supplemented with deep behavioral detail: the internal routing to SEC EDGAR vs grounded pipeline, the full verdict list, and a critical warning that 'could_not_verify' indicates a failed check (not evidence) while 'unsupported' means no source found. Goes far beyond what annotations 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?

Though longer than typical, it is efficiently organized: starts with trigger phrases and purpose, then usage, behavioral details, return values, an IMPORTANT caveat, and a note on efficiency. Every sentence earns its place, and the structure helps the agent quickly grasp key semantics.

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?

Compensates for the lack of an output schema by listing all possible verdicts, explaining the meaning of could_not_verify vs unsupported, describing the return value (with citation and reasoning), and clarifying the composite nature (replaces 4–6 calls). No critical information is missing for a complex tool.

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

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

Schema description coverage is 100% for both parameters. The description adds context about tolerance override (e.g., 'set 1–2 for hallucination detection') but the schema already explains the parameters well, so the description provides marginal additional value.

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

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

States a specific verb+resource+scope: 'natural-language claim verification against authoritative sources.' Trigger phrases ('fact check', 'verify the claim that…') make intent unmistakable. Distinct from sibling tools by describing two pathways (SEC EDGAR structured vs grounded pipeline), clearly differentiating it from general Q&A or research tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives guidance for company-financial vs other claims. Lacks explicit when-not-to-use or named alternatives, but provides clear context and even notes it replaces 4–6 sequential calls, which is strong usage guidance.

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