Data Calgary

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) already convey safety. The description adds valuable context: the default model is free, using Anthropic requires a BYO key and direct payment, and the return format includes per-model score/confidence/signals/raw_response plus a combined view. 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?

Three sentences, front-loaded with the core purpose, then default/cost, then returns and use cases. No redundant words, every sentence earns its place. Excellent structural efficiency.

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

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

For a tool with 4 parameters and no output schema, the description covers the return structure (per-model object + combined view), the main use cases, and key behavioral notes. It lacks only deeper edge-case information (error handling, rate limits), which are not critical given high annotations and schema coverage. Very solid overall.

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 meaning by noting the default model (Workers AI Llama-3.3-70b free) and explaining the cost/ownership of using _apiKey ('BYO key — you pay Anthropic directly for those calls'). This is useful behavioral context that the schema does not provide, nudging the score to 4.

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

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

The description uses a specific verb+resource construction: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from siblings like ask_pipeworx (which asks questions) and scan_competitor_ai_presence (which may have a different focus). It also outlines the return structure and 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?

Explicit use cases are given ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which clarify when to use. The description also explains the default model and optional Anthropic key with cost implications. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: it routes to a large catalog of verified sources, fills arguments automatically, returns a structured answer, and provides stable pipeworx:// citation URIs. This tells the agent what kind of result to expect and how the tool operates.

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

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

The description is longer than average but dense and front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). Nearly every sentence contributes domain scope, expected behavior, or usage examples. The final breaking-news sentence is slightly awkward, but it still clarifies that live news is already covered.

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 routing tool with no output schema, the description covers the essential context: what kind of questions to ask, what the tool does internally, that it returns a structured answer, and that answers carry citation URIs. It does not explain exact output structure or potential delays, but the lack of an output schema is partially mitigated by the clear citation behavior.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value with natural-language trigger phrases and numerous example queries that illustrate exactly how to phrase the single 'question' parameter. It also makes it clear the user only needs to provide a question, not tool arguments, because routing and argument-filling are handled internally.

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?

Describes a specific action: route a natural-language question across 5,798 tools and return a structured, cited answer. The description clearly positions it as a fact-question answering router distinct from web search, and the examples reinforce that scope.

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 when-to-use guidance: 'PREFER OVER WEB SEARCH', trigger phrases like 'what is', 'look up', 'find', and many concrete examples, even saying to use it when web search could also answer. It does not explicitly name situations where a sibling tool like ask_pipeworx_grounded or deep_research should be preferred, so it stops short of a 5.

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

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

This description goes well beyond the annotations by explaining that candidate routing improvements may be enabled live, that no candidate is currently active, and that the tool falls back to nothing because it is a full working router. This gives an agent a realistic picture of experimental variability and current behavior without contradicting the readOnly, idempotent, and openWorld hints.

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

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

The description is slightly wordy with parentheticals and repetition of the idea that it matches ask_pipeworx, but most sentences add distinct information about identity, current state, usage, purpose, and no-fallback behavior. It is front-loaded with the beta relationship and remains useful despite the extra detail.

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

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

Given the annotations already cover safety and idempotency, and the schema covers parameters, the description provides sufficient extra context about current routing state and experimental risk. It also mentions the same response shape as ask_pipeworx, which is useful since there is no output schema. A concrete example or a bit more detail about the routing behavior would make it more 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%, so the schema already documents parameters and the baseline is 3. The description adds no parameter-specific semantics beyond saying the tool has the same arguments as ask_pipeworx; it does not clarify the required question parameter or the alias relationships beyond the schema.

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

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

The description clearly identifies ask_pipeworx_beta as the beta version of ask_pipeworx and a universal router with the same 5,798 tools, arguments, and response shape. This distinguishes it from the stable ask_pipeworx sibling by its experimental routing improvements, though it relies on the reader knowing what ask_pipeworx itself is rather than defining the tool's core behavior from scratch.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, which gives a clear usage condition. It also notes that no candidate is currently active so it matches ask_pipeworx exactly. However, it does not explicitly state when NOT to use it or direct users to a specific stable 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?

The description goes well beyond the annotations by disclosing exact success and refusal return shapes, enumerating refusal reasons, and stating that the answer uses ONLY the tool result. It also explains the extra LLM call cost. This level of behavioral transparency helps an agent predict outcomes and avoid unsupported claims.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, return shape, refusal behavior, usage guidance, and cost trade-off. It is front-loaded with the core purpose and structured so an agent can quickly extract the key decision-relevant facts.

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

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

Despite having no output schema, the description fully covers return values, refusal cases, and the key behavioral constraint against inventing facts. Combined with the read-only, idempotent annotations, the agent has everything needed to invoke and interpret the tool safely.

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 documents the 'question' parameter and its aliases. The tool description does not add parameter-specific guidance, but it doesn't need to given the schema coverage. 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 specific mode: a hallucination-resistant answer mode for high-stakes reads that routes like ask_pipeworx but extracts answers only from tool results. It also distinguishes itself from ask_pipeworx by emphasizing grounded evidence and explicit refusals. This gives an agent a precise mental model of what the tool does and how it differs from its closest sibling.

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

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

The description explicitly states when to use this tool: whenever an answer will be quoted, cited, or acted on and facts must not be invented. It also names the alternative (ask_pipeworx) and explains the trade-off: this costs one extra LLM call, so casual lookups should prefer ask_pipeworx. This is clear, practical routing guidance.

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

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

The description goes far beyond the annotations by disclosing resolver contracts (market_match_confidence, alternatives, suggestions), safety short-circuit behavior on low-confidence matches, closed-market status handling, wide-spread illiquidity warnings, cancellation-rule parsing with ev_impact, and news fallback details (429s, retry_after_sec). This level of edge-case transparency is exceptional.

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 tightly structured with capital-letter section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Each section provides non-redundant information. It is dense and could be shortened, but the structure keeps it navigable and every sentence earns its place.

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

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

Given there is no output schema, the description must explain return values, and it does so comprehensively: result.market, result.analysis, result.evidence, market_match_confidence/score/alternatives, parent_event fields, news metadata, and blocking statuses. It also explains resolution-rule risk and safety paths, making the description fully sufficient for agent invocation.

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

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

Schema description coverage is 100%, so the structure already fully documents the three parameters. The description adds no unique parameter-level semantics beyond what is in the schema; it instead focuses on behavioral and output details. 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+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like polymarket_arbitrage or ask_pipeworx by describing the fan-out to category-specific data packs and the market-vs-model comparison output.

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 use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains input formats (slug, URL, question text). However, it does not explicitly state when not to use this tool or name alternative sibling tools for specific scenarios, so this is not a full 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that results include dataset names/descriptions/resource ids, which is useful return-value context but lacks deeper behavioral detail like pagination or auth nuances. 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?

One compact sentence captures purpose, resource, and return value without waste. It is front-loaded and every clause contributes 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?

Given no output schema, the description does well to list return fields. It also connects to calgary_query. It lacks explicit mention of pagination or rate limits, but those are covered by schema parameter descriptions, so the description is largely complete.

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

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

Schema description coverage is 100%, so parameters are already self-explanatory. The description adds nothing about parameter syntax or formats beyond the schema, so the 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 uses a specific verb ('Search') and names the exact resource ('Calgary open-data catalogue'). It also states the return payload (dataset names, descriptions, Socrata resource ids), which clearly distinguishes it from sibling tools like calgary_recent and calgary_query.

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

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

The description explains that returned resource ids are for use with calgary_query, providing clear 'next-step' guidance. It doesn't explicitly exclude other tools or mention calgary_recent, but the keyword-search workflow is well implied.

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, and idempotentHint, covering safety. The description adds context on the raw SoQL nature, the full range of clauses supported, and the resource id format, which helps the agent understand the tool's behavior beyond structured hints. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence earns its place. It avoids unnecessary detail while giving essential usage pointers.

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

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

Given the tool has no output schema and 8 parameters, the description provides enough context to invoke it correctly: how to get resource ids, the full SoQL capabilities, and the resource id format. It relies on the schema for detailed parameter limits, which is acceptable. It could be more complete by mentioning pagination or error handling, but annotations and schema cover most operational aspects.

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

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

The input schema provides 100% coverage with each parameter containing a description, so the baseline is 3. The description adds a little value by listing the SoQL clauses and giving the exact resource id format, but this is largely redundant with the schema's per-parameter descriptions. No meaningful additional parameter semantics are introduced.

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 runs a raw SoQL query against any Calgary open-data resource using a Socrata id. It uses a specific verb ('run') and resource ('Calgary open-data resource'), and distinguishes itself from siblings like calgary_datasets and calgary_recent by focusing on direct data querying rather than listing or retrieving common datasets.

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 tells the agent to use calgary_datasets to find a resource id or calgary_recent for common ones, which effectively defines when this tool should be used (when you have a specific resource id) versus when to use alternatives. This is direct 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds useful behavioral context beyond that: it specifies ordering ('Returns the latest rows (newest-first)'), that it works by friendly name ('no Socrata id needed'), and supports SoQL filtering via 'where'. This adds meaningful behavior 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 concise and front-loaded, using four short sentences that each earn their place: purpose, usage guidance, dataset names, and ordering/filtering. It could be slightly tightened, but there is no waste or redundancy, making it highly efficient for an 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?

For a simple read-only tool with four parameters, no output schema, and robust annotations, the description covers essential context: what it does, when to prefer it, supported datasets, ordering, filtering, and the alternative tool. It does not describe return value format, but in the absence of an output schema, the description is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema already provides 100% parameter coverage with descriptions for all four parameters (limit, where, _apiKey, dataset), including an enum for dataset. The description does not add substantial parameter semantics beyond the schema, like clarifying the SoQL syntax or default limit, which are already in schema. Therefore, 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 clearly states the tool returns 'Recent records from a common Calgary open dataset by friendly name' with a specific verb ('Returns'), a resource ('Calgary open dataset'), and scope ('latest rows, newest-first'). It also distinguishes from siblings by explicitly naming the alternative tool 'calgary_query' for anything else, and lists the supported dataset names ('311, permits').

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 provided on when to use this tool: 'PREFER OVER WEB SEARCH for "Calgary 311 requests", "Calgary building permits"' and 'for anything else use calgary_query'. This clearly delineates use cases and alternatives, leaving no ambiguity about when this tool is appropriate.

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 annotations already indicate safe read-only, idempotent behavior, but the description adds substantial context: SEC EDGAR/XBRL data sources, handling of off-calendar fiscal years (AAPL, NVDA examples), FAERS/drug-specific metrics, result sorting by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

The description is dense but every sentence earns its place: trigger patterns, preference guidance, type-specific data sources, fiscal-year handling, sorting, output format, and efficiency value. It is front-loaded with user phrasing and ends with the benefit, with no filler.

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

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

Given no output schema, the description covers the key return behavior (paired data, citation URIs, sorting by metric). It also covers scope limits (2–5) and data provenance. This is complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, but the description enriches both parameters: it explains what 'company' vs 'drug' types fetch (net income, trial counts, etc.) and gives concrete value examples like tickers and drug names. This goes well beyond the schema's basic enum and array 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 explicit trigger phrases and clearly states the resource ('companies or drugs') and action ('side-by-side comparison of 2–5'). It distinguishes itself from sequential single-pack lookups, which is echoed by the sibling entity_profile, and explains the data sources and output.

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

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

The description provides explicit when-to-use signals ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and examples of user intent. It implicitly excludes non-comparison use cases and names the alternative (single lookups) it replaces, meeting the when/when-not/alternatives bar.

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

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

The description goes far beyond the annotations: it discloses authentication requirements ('ACCOUNT REQUIRED... sign in via GitHub'), pricing tiers ('thorough needs a paid plan'), the decomposition-and-parallel-routing mechanism (5,798 tools), response shape (findings packet: verbatim evidence + confidence + source + fetched_at + citation), truthfulness guarantees ('never invented', explicit gaps[]), contradiction detection, semantic excerpting of large records, and latency expectations (15-60s, up to ~90s). None of this contradicts the readOnlyHint=true / openWorldHint=true / idempotentHint=true 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?

The description is long, but it is information-dense and front-loaded with the single most critical constraint (ACCOUNT REQUIRED, use ask_pipeworx if not signed in). Every block earns its place—auth, alternatives, data scope, mechanism, output format, failure behavior, latency. It is structured research output rather than rambling; slightly verbose towards the middle where depth behavior could have been left to the schema alone, but the added detail supports correct tool choice.

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

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

Given no output schema, the description fully explains return values (findings packet with evidence/confidence/source/timestamp, gaps[], contradictions[], hop field, citation_uri) — exactly where the burden falls. It also covers auth prerequisites, cost gating, latency, and exclusion routing. An agent has everything needed to decide, call, and interprete the result correctly. Nothing material is missing for a tool of this complexity.

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

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

Schema coverage is 100% so the baseline is 3: the schema already documents question and depth in detail, including what each depth level does. The description adds meaningful value beyond the schema by flagging that depth:'thorough' requires a paid plan and tying the returned artifacts (gaps[], contradictions[], hop field) to depth choices. It reinforces but doesn't merely repeat the schema; minor duplication of the depth semantics keeps it shy of 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?

States a specific verb ('research') and a precise resource ('1517 STRUCTURED data sources' — SEC, FRED, FDA, USPTO, etc.), and explicitly differentiates itself from alternatives: 'this is NOT open-web search' and 'for a single lookup use ask_pipeworx.' An agent can immediately tell what this tool is for and how it differs from its siblings without inspecting schemas.

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

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

Gives explicit selection criteria: 'If you are not signed in, use ask_pipeworx instead — it works on every tier,' and 'For a single lookup use ask_pipeworx.' It also states what the tool is 'Best for' (broad/multi-part questions over structured data) with concrete example queries. Exclusions and alternatives are named directly, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable disclosure about the return payload (top-N tools with full schemas, ready to call directly) and that no second lookup is needed – context beyond annotations that 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 front-loaded with the core purpose, then gives a categorized usage context, return format, and a clear action directive. The domain list is long but directly useful for guiding search queries, and every sentence earns its place without 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?

With no output schema, the description properly explains return values (tool names, descriptions, schemas) and convinces the agent that results are directly callable. Combined with the schema examples and usage guidelines, this makes the tool fully self-contained for an agent deciding to invoke it.

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

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

Input schema covers 100% of parameters with descriptions, including aliases and limit defaults. The description does not add parameter semantics beyond the schema, so baseline 3 applies; the 'top-N' mention aligns with the limit parameter but adds no syntax detail.

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 with a specific verb ('Find tools' or 'discover what tools exist') and resource (tools by data/task). It distinguishes itself from sibling domain-specific tools by positioning as a meta-search for the tool catalog, and explicitly notes 'Call this FIRST' – a clear differentiator.

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 context for when to use: browsing/searching/discovering tools, with a domain list, and explicitly instructs 'Call this FIRST when you have many tools available.' It implies a when-not (if you already know the tool, use it directly) with 'not just one answer,' which serves as an exclusion signal.

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 cover safety (readOnly, idempotent, non-destructive), so the description adds substantial behavioral depth: it names all fan-out sources, explains soft-failure for USPTO patents, defines sources_used/sources_failed semantics, notes that empty fda_products is expected for non-biologic companies, and specifies private-company behavior. 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 it is dense and organized: triggers, preference rule, fan-out sources, each return field, and failure semantics. It is front-loaded with usage signals rather than buried definitions. Some repetition of schema information costs a point, but the length is largely earned 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?

With no output schema, the description must carry the full burden of explaining return values and failure modes. It does so thoroughly: every field of the returned profile is enumerated, sources_used/sources_failed semantics are defined, and realistic edge cases (private company, small-molecule drug company, patent API sunset) are addressed. This is complete for safe invocation.

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

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

Schema coverage is 100% with good descriptions for type and value, so baseline is 3. The description adds meaningful context beyond the schema: type values are interchangeable, value can be a ticker, zero-padded CIK, or name, and name resolution happens via SEC EDGAR's company-name match. This clarifies invocation semantics further.

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 states the core action: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes this from narrower SEC/XBRL/news lookups and from siblings like compare_entities by emphasizing single-entity holistic profiling.

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

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

It explicitly says 'ALWAYS PREFER' this over chaining single-pack lookups when the user wants a holistic view, supplies trigger examples, and clarifies edge-case usage: names resolve via EDGAR, private companies return resolved:false, and empty sections are expected, not errors. This gives clear when-to-use and when-not-to-worry 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 flag destructiveHint=true and idempotentHint=true. The description adds context by mentioning clearing sensitive data, but does not disclose side effects beyond deletion (e.g., irreversibility) or any potential edge cases. With annotations covering the core safety profile, this is acceptable but not rich.

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

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

Two sentences, front-loaded with the primary action, and no filler. Every word contributes to understanding purpose and usage. Excellent 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?

For a trivial tool with one parameter, destructive hint, and no output schema, the description is sufficient. It covers what, when, and how to pair with siblings. It could mention that deletion is permanent, but the destructiveHint already implies this, so the completeness is high.

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 'key' is already described as 'Memory key to delete.' The description repeats 'by key' but adds no additional semantic detail (e.g., key format, case sensitivity, or behavior for missing keys). Baseline 3 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 states a specific verb ('Delete') and resource ('previously stored memory by key'), which clearly distinguishes it from related tools like remember and recall. The purpose is 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?

Provides explicit when-to-use guidance: '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'), but does not explicitly state when not to use it or alternatives, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by revealing the process: fetches the page, extracts title/description/key links, and emits a text blob. This informs the agent about network access and output format 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?

Two sentences, front-loaded with the core purpose and method, followed by practical use cases. Every sentence earns its place with no redundancy.

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

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

Given no output schema and good annotations, the description fully covers the tool's purpose, method, output format, and usage scenarios. It is sufficiently complete 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%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema provides; it only mentions 'any URL' and link extraction, which is already implied. No compensation needed.

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 has a specific verb 'Generate' and resource 'production-ready llms.txt file for any URL', clearly stating what the tool does. It distinguishes from siblings by specifying the exact outcome: a standard llms.txt markdown format ready for site-root deployment.

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

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

The description explicitly lists three concrete use cases: getting a client's site indexed, drafting for your own project, and auditing competitor AI presence. It does not mention alternatives or exclusions, but the usage context is very 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 declare readOnlyHint and idempotentHint, covering safety. The description adds valuable context by listing exact return fields (id, type, params, created_at, last_fired_at, fire_count), which is useful for agents. No contradictions.

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

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

Two sentences, each earning its place. First states purpose and return fields, second gives usage guidance. Front-loaded and efficient with no wasted words.

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

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

Despite lacking an output schema, the description fully explains what the tool returns. The optional parameter is documented in schema, and the use case is clearly stated. For a simple list tool with rich sibling context, this is complete.

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

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

Schema coverage is 100% for the single parameter include_inactive, so baseline is 3. The description mentions 'active subscriptions' which implicitly aligns with the default false, but it does not explicitly explain the parameter's meaning beyond the schema. No added value beyond schema, but no shortfall.

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 lists the caller's active subscriptions, which is a specific verb+resource pairing. It also differentiates from sibling tools like subscribe/unsubscribe by focusing on review/listing.

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

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

Explicitly states when to use: to review current monitoring before adding more or to find an id to cancel. This provides clear context and aligns with sibling tools, giving implied when-not-to-use guidance.

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

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

Annotations only indicate non-read-only/non-destructive/null safety hints; the description adds substantive behavioral context: rate limits, free usage, claim_token creation and later lookup, daily digest review, and roadmap impact. There is no contradiction with 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?

Although the description is a long paragraph, it is front-loaded with the core purpose and every subsequent sentence adds actionable detail: usage rules, exclusions, content guidance, claim-token mechanics, and rate limits. No sentence feels wasted, and em-dash separators help group related ideas.

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

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

With no output schema, the description explains the claim-token return flow and the two invocation modes (submit feedback vs. check a prior report). It does not explicitly state what a successful submission returns when the user is authenticated, leaving a minor return-shape ambiguity. Otherwise, it is thorough enough for correct selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful extra semantics beyond the schema, especially for claim_token (exact call pattern and what it returns) and message content guidance ('don't paste the end-user's prompt'). It does not add much beyond the schema for type/context, but the added parameter workflow detail justifies a 4.

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

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

The description opens with a concrete action—telling the Pipeworx team something is broken, missing, or needs to exist—and specifically names the feedback categories. It clearly distinguishes itself from sibling tools like ask_pipeworx by focusing on reporting issues about Pipeworx tools rather than retrieving information.

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, data_gap, praise), explicit when-not-to-use guidance (tools from other MCP servers, end-user prompts), and directs uncertain agents to use the Pipeworx tool list. This is exemplary usage 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 (readOnlyHint=true, destructiveHint=false), the description adds valuable behavioral context: the data source ('derived from CF analytics-engine'), privacy ('no PII'), the output shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). 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 four sentences, front-loaded with the core purpose, then use cases, then data provenance and caching. Every sentence adds useful information with no redundancy or fluff, though it is slightly longer than the two-sentence ideal.

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 read-only tool with one optional parameter and no output schema, the description sufficiently covers what it returns, when to use it, data source, privacy, and caching. It does not detail the exact return structure beyond '(pack, tool, count)', but this is adequate given the simplicity of 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?

The input schema already provides full description for the only parameter `window`, including its enum values and semantics about short vs long windows. The tool description merely repeats '24h, 7d, or 30d' without adding new meaning, so with 100% schema description coverage, 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 clearly states the tool 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)', providing a specific verb and resource. It is inherently distinct from siblings by focusing on trending agent calls, but it does not explicitly name an alternative tool for comparison.

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

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

The description lists three concrete use cases: 'discovering what data sources are hot for current events', 'confirming a popular tool is the canonical choice before asking your own question', and 'seeing whether your use case aligns with what most agents need'. This gives clear context for when to use it, though it lacks explicit exclusions or alternative tool suggestions.

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, and the description adds substantial context: scan scope (top ~200 markets), semantic anchor threshold (≥0.30 Jaccard), partition placeholder filter (>20% yields null), and fill-check behavior (prices against live CLOB depth, 1000 shares/leg). 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 lengthy but tightly structured with bold section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the core purpose and usage, and every sentence carries operational information, though it could be slightly more concise.

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 defines the response shape (opportunities[], partition_check, skipped_low_similarity) and edge cases (null arb signal, thin legs). It covers invocation modes, filters, and fill-check caveats, making it sufficient for an agent to select and call 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 descriptions already cover both params, but the description enriches them with concrete slug examples ('fed-decision-may-2026'), topic seeds, and behavioral differences between event and topic modes. It also confirms that full Polymarket URLs are accepted, reinforcing 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by naming the arbitrage focus and explicitly invoking the fill check.

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

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

It provides explicit mode selection: 'event (recommended for a specific market)' vs 'topic (for cross-event scanning),' with concrete examples. It also directs custom sizing to 'polymarket_fill_risk' and warns when not to trade ('realizable_edge_pp ≤ 0 ... do not trade it'), giving clear when-to-use and when-not-to 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 (readOnly, openWorld, idempotent, non-destructive), the description discloses extensive behavioral details: five model families, exact response segments, edge_pp_net after slippage, Kelly fractions, liquidity filters, a 24h-move warning, diagnostics for empty segments, and 1h KV-level caching. This greatly exceeds what annotations alone convey.

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

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

The description is dense but well-organized with uppercase section labels, and every sentence adds value. It avoids redundancy with the schema, instead providing context (e.g., slippage rationale, model family explanations). No filler or 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?

With no output schema, the description fully explains return structure: by_segment fields, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains edge cases like empty segments and the unreliability of Fed signals without paid data, making the tool's behavior predictable.

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

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

Although schema coverage is 100%, the description adds cross-parameter context and rationale. It groups knobs as 'TRADEABLE-EDGE KNOBS' and explains how min_liquidity/max_spread_pp drop unrealizable edges, and how min_partition_leg_kelly applies to per-leg Kelly inside top_legs, which is not obvious from 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 states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is clearly differentiated from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreements and the 'what should I bet on today' use case.

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: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains the tool's purpose and even notes exclusions (Fed bets excluded from ranking), but it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.

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

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

Annotations only declare read-only, idempotent, and non-destructive properties. The description adds substantial behavioral context: the 60-day snapshot TTL limits history depth, snapshots are written only on cache-miss (gaps indicate no scan), and decay is computed from daily closes of edge_pp_net (net of default slippage), not intraday. 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 lengthy but meticulously structured: it opens with purpose, then details the args, response fields (tracked[], expired[], snapshot_dates[]) each with clear explanations, and ends with limits. Every sentence serves a purpose, and bold labels improve parseability for agents. It is as concise as the complexity allows.

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?

Since there is no output schema, the description carries full responsibility for explaining return values. It comprehensively describes all three response components, including the time-series, trend and decay fields, lifespan, and snapshot dates. It also covers the TTL and data-gap limitations, making the tool's behavior fully predictable 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% (both params described), so the baseline is 3. The description adds meaning by explaining 'window (snapshot family)' and clarifying days as 'lookback' with 'max 30' vs schema's 'clamp 2-30'. While the min clamp is omitted in the description, the overall context adds value without contradicting 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 clear statement of the tool's role: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It further answers a specific question ('how long has this edge existed and is it shrinking?') and explicitly differentiates from the sibling polymarket_edges tool by focusing on historical snapshot analysis rather than current edge 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 implies usage context by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), making clear when this tool should be used. However, it does not explicitly name alternative tools or provide exclusion criteria, so it falls short of a 5.

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

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

Annotations already mark the tool read-only, but the description adds behavioral detail: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and identifies thin legs and forced directional risk. It also reveals the auto side selection logic in basket mode, going well beyond the safety 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 dense but well-structured, front-loaded with the core purpose and then branching into modes and usage. While lengthy, each section adds essential detail for a two-mode tool, and the final sentence justifies use without redundancy.

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

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

Given no output schema, the description enumerates key return fields like top_of_book, vwap_fill_price, capture_ratio, and verdict. It also covers both operating modes, edge-case behavior (partial fills), and provides use-case context, making it self-sufficient 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%, but the description adds meaning by explaining how parameters interact—e.g., 'REQUIRES one of market or event' and the dual interpretation of size_usd (spend/proceeds vs settlement notional). This goes beyond the schema's field-level descriptions by clarifying the mode-dependent roles.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly identifying the tool as a fill-risk checker. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on execution feasibility rather than opportunity detection.

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 states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' naming the exact sibling tools. It also explains why—theoretical overround on thin books is not capturable and partial fills create unhedged positions—providing clear situational 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?

This description goes far beyond the readOnly/openWorld/idempotent annotations: it explains compatibility codes, the pairing_unverified limitation, fee treatment (gross vs net), temporal_alignment null semantics, and that unknown legs are never paired. This gives an agent accurate expectations about outputs and caveats. There is no contradiction with the annotations.

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

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

The description is long, but it is well-organized into labeled sections: modes, response contents, safety fields, codes, flags, skipped legs, fees, and a final caveat. It front-loads the core purpose and the main non-obvious warning. Some repetition exists, but with no output schema the detail is largely functional rather than filler.

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

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

Given the complexity and the absence of an output schema, the description is remarkably complete. It documents the response shape (raw prices, top_spreads_pp, flags), the meaning of compatibility codes, temporal alignment behavior, skipped leg counters, and fee disclosures. An agent has enough context to invoke the tool and interpret its results correctly.

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

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

The schema already covers all three parameters at 100% with values and examples. The description adds meaningful semantics beyond that: topic auto-fetches matching events on each venue, explicit ticker/slug override the topic-mapped side, and both modes run the identical token-overlap matcher. This is more than a baseline schema-only situation, but not a full replacement for the schema.

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

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

The description states a specific function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly differentiates this from a tradeable arbitrage edge by calling the result gross, and it explains the two modes. It does not explicitly name sibling alternatives like polymarket_arbitrage, so it stops short of a perfect sibling differentiation.

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 concrete usage guidance: use topic shortcuts for ten pre-mapped macro events, or supply explicit kalshi_event_ticker/polymarket_event_slug for custom pairings. It also warns that pre-mapped topics often return compatibility warnings and are not necessarily tradeable. It does not explicitly state when to choose this tool over related sibling tools, so exclusionary 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: the scoping detail ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of listing all keys when the key argument is omitted. This enriches agent understanding of the tool's operational boundary.

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 composed of four sentences, each earning its place: core action (first sentence), use cases (second), scoping (third), and sibling relationship (fourth). It is front-loaded with the main verb and contains no filler or redundant information.

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

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

For a simple read-only tool with one optional parameter, strong annotations, and no output schema, the description covers purpose, usage scenarios, scoping, and related tools. It does not specify return format or error behavior, but the tool's low complexity and rich annotations make this a minor gap rather than a critical omission.

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%: the only parameter 'key' already has a description ('Memory key to retrieve (omit to list all keys)'). The tool description reinforces this with examples and restates the omit-to-list behavior, but adds no new syntax, format, or edge-case details beyond what the schema already provides. 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 action with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It explicitly distinguishes between retrieval and listing, and names sibling tools (remember, forget), which differentiates it from alternatives.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier' and gives concrete examples (target ticker, address, research notes). It also names alternatives by saying 'Pair with remember to save, forget to delete', which clarifies when to use this tool versus its siblings.

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

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

Annotation Contradiction: readOnlyHint=true conflicts with the description's statement that 'Set mark_read:true to flag returned events read so the next call only shows newer ones' — this implies persistent state mutation. While the description otherwise discloses payload contents and feed behavior, the contradiction with the read-only annotation forces a score of 1.

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 concise, front-loaded sentences cover purpose, return payload, filtering, side effects, and polling suitability. 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?

Despite no output schema, the description explains what each event carries (source, citation_uri, raw payload) and how the tool behaves (filtering, mark_read side effect, polling). Parameters limit and unread_only are adequately covered by the schema, so the description is complete for this tool's complexity.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by giving a concrete type example ('sec_8k') and clarifying the consequence of mark_read (next call shows only newer events), going beyond the schema's short 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 'Pull fired events from your subscription feed', a specific verb and resource. It distinguishes this tool from siblings like list_subscriptions and recent_changes by focusing on fired alert events with payload details.

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 clear context: filtering by type and/or since, polling suitability ('Polls work fine'), and an alternative access method via a direct URL. It stops short of explicitly naming sibling alternatives or stating when not to use this tool, so it misses the top score.

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

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

The description discloses multi-source fan-out, GDELT→GNews fallback on rate limits/5xx, and the PatentsView API sunset causing soft-fail, which goes beyond the readOnly/idempotent annotations. It also describes the return structure (changes[], total_changes, citation URIs), providing a comprehensive behavioral model.

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

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

While longer than two sentences, the description is well-organized and dense with useful information, avoiding repetition. The opening query examples are front-loaded for quick relevance matching, and the later sections on sources, parameters, and alternatives each add necessary context.

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 trigger phrases, source behaviors, parameter options, output structure, and the key alternative tool, which is sufficient given the absence of an output schema. It even notes external API limitations, making it robust for an agent to set expectations.

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

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

The input schema already covers all three parameters with detailed descriptions, including `since` format examples and the 30d/1m recommendation, so the description adds no new parameter meaning. Baseline 3 is appropriate given 100% schema coverage; any extra is redundant.

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 aggregating SEC/GDELT/GNews/USPTO data for a company over a time window, triggered by natural-language queries like 'What's new with X'. It differentiates from entity_profile by explicitly naming the alternative, making its scope unmistakable.

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

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

It provides explicit when-to-use signals via example queries and states when to use entity_profile instead, giving a clear exclusion criterion. It also explains the parallel fan-out and fallback behavior, helping the agent decide based on user intent.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and safe repetition (idempotentHint=true). The description adds persistence details: identifier scoping, 24-hour retention for anonymous sessions, and persistent memory for authenticated users. It does not list failure modes or overwrite behavior, but the additional context is beyond annotations.

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

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

Five sentences, each providing distinct value: action, use-case, storage format, persistence policy, and sibling relationships. No redundant phrases.

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

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

Covers purpose, when to use, storage mechanics, retention, and integration with recall/forget. No output schema is defined, so no return-value explanation is required. Simple two-string tool is fully addressed.

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 with detailed descriptions and examples. The tool description adds general usage context but no new parameter-specific semantics; the baseline of 3 applies.

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

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

The description uses the verb 'save' with a clear object ('data the agent will need to reuse later') and explicitly names sibling tools 'recall' and 'forget' to differentiate retrieval and deletion. This distinguishes it from the 30+ sibling tools.

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

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

It states when to use ('when you discover something worth carrying forward'), provides concrete examples, and says 'Pair with recall to retrieve later, forget to delete,' explicitly mapping alternatives. This goes beyond implied usage into explicit exclusions.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral detail: ambiguous matches return figi_candidates and assert nothing, unresolved identifiers are stated explicitly, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple endpoints. 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 purpose and usage are front-loaded, but the company description is one enormous run-on block with many parenthetical asides. Although dense and informative, it is not concise and is disproportionately long for a two-parameter tool. Better structure would split the company details into readable clauses.

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 resolver with no output schema, the description covers input variants, return semantics (figi_candidates, unresolved fields, source labels), and failure behavior. An agent has enough context to invoke the tool correctly and interpret ambiguous outcomes without guessing.

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

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

Schema coverage is 100%, but the description adds meaning well beyond the schema: accepted input forms for company (ticker, CIK, ISIN, exact issuer name), the ISIN-to-LEI behavior, the bond issuer exact-name caveat, and drug examples. This materially helps an agent populate the two 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 names a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It opens with concrete user phrasings and explicitly frames the tool as the name-to-ID lookup step, which clearly distinguishes it from siblings like entity_profile or compare_entities.

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

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

It gives an explicit cue: 'Use FIRST whenever you have a name but need an ID.' It also clarifies supported types and what the tool replaces. However, it does not name alternatives or state when not to use it (e.g., when a canonical ID is already known and a profile is wanted), so it lacks exclusions but has clear context.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it performs a multi-probe comparison via ai_visibility_check and returns a ranked summary, which goes beyond the annotations and clarifies the internal process.

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 concise sentences: purpose, mechanics, use case, and output format. Every sentence earns its place, with no repetition 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 tool with only 4 params and no output schema, the description covers the behavior, return format (ranked list with score/confidence/signal density), and use case. Combined with rich annotations and schema, it leaves no critical gaps.

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

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

Schema description coverage is 100% with detailed parameter docs, including supported models, optional API key, shared context, and entity ordering semantics. The description reinforces the 'brand + competitors' idea but adds no extra parameter 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?

Clearly states the tool compares AI visibility across entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This specific verb+resource+outcome distinguishes it from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison).

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

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

Explicitly frames usage for competitive AI-marketing audits and provides a concrete example question. While it doesn't name alternative tools or exclusions, the context is specific and actionable, making it easy to decide when to use.

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

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

Annotations cover read-only and idempotent hints, but the description adds valuable behavioural context: it fans out across two services, partial failures degrade gracefully, and a 5-30s timing risk for bundlephobia's first measurement. This goes well beyond what annotations convey.

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

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

The description is dense but every sentence adds value: it front-loads the core purpose, lists key outputs, notes ecosystem limitations, and explains failure handling. No pointless 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 composite tool with no output schema, the description covers all essential aspects: what it does, when to use it, what it returns, failure modes, and ecosystem scope. It is fully adequate 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 100% coverage with descriptions for both parameters (package name and version). The description adds minimal extra semantics (e.g., example 'lodash'), and does not clarify defaults or formats beyond the schema, so 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 this is a composite 'should I add this npm package' check, naming both deps.dev and bundlephobia. It is specific about the resource and scope, and distinguishes itself from sibling tools by being the only npm-focused dependency scanning 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 given: 'Use whenever an agent asks "is X safe / popular / small"...' It also provides a clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' effectively naming 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 declare readOnlyHint/openWorldHint/idempotentHint, but the description adds substantial behavioral context: truncation at 200K chars with flagging, embedding model (BGE-base-en), overlapping windows, and output includes offsets and similarity scores. This exceeds the baseline set 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 front-loaded with the core action, then use case, pairing, and technical details. Every sentence provides distinct value—no fluff. Length is appropriate for the complexity, and structure moves from high-level to implementation specifics.

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

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

Despite no output schema, the description covers return values (passages with offsets and similarity scores), input constraints (200K chars), usage context, and technical behavior. It fully equips 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%, so baseline is 3. The description adds meaningful semantics: clarifies 'text' is 'already pulled' content (not a URL/id), gives query examples ('supply-chain risk'), and explains limit as top-N passages. This goes beyond the schema's brief descriptions, justifying a 4.

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

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

The description uses a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings like ask_pipeworx by emphasizing it operates on text you already pulled, and explicitly pairs with ask_pipeworx_grounded. The scope is unambiguous and actionable.

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?

States exactly when to use: 'Use when the record is too big to cram into the prompt.' Also provides an alternative workflow with ask_pipeworx_grounded, and explains benefits (saves context, verifiable quotes). This is explicit usage guidance with a named 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?

Annotation Contradiction: The description says 'Returns the new subscription id,' implying a fresh subscription is created on each call, while annotations declare idempotentHint=true, which means repeated identical calls should not create duplicate resources. This is a direct contradiction. The description also does not clarify deduplication behavior or whether an existing subscription ID is returned on retry.

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

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

The description is dense but well-structured: it opens with the core purpose and auth requirement, then systematically covers supported types with examples, and finally explains delivery channels. Every sentence carries necessary information, and the front-loading is effective.

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

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

The description is highly complete for a create operation: it covers auth requirements, return value, supported types, delivery options, and operational constraints (verification, caps, auto-disable). The only notable gap is the lack of clarity around idempotency, which is also the source of the annotation contradiction, so it does not fully achieve a 5.

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

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

Although schema coverage is 100%, the description adds substantial value beyond the schema by providing concrete examples for each subscription type (e.g., items:["5.02"], topic:"fed", series_id:"UNRATE"), and detailing delivery constraints (verified phone, 10/day cap, webhook signing secret). This goes far beyond the baseline.

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

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

The description uses a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly distinguishes it from siblings like 'list_subscriptions', 'unsubscribe', and 'recent_alerts' by focusing on the creation action and the target resource.

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 when to subscribe, enumerates supported types, and even references 'recent_alerts' for pulling from the always-on feed. It does not explicitly say 'use this instead of X' or list exclusions, but the context is sufficient for an agent to decide.

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 non-destructive, and the description adds substantial behavioral context: the output structure (category-bucketed examples with tool+argument shapes), that it is drawn from a live catalog of thousands of tools, and how invocation with or without `topic` changes results. 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 every sentence contributing either example queries, return behavior, or usage guidance. The list of categories is long but informative; minor verbosity in the opening example string is acceptable given the tool's onboarding purpose.

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

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

For a tool with one optional parameter and no output schema, the description fully covers purpose, behavioral details, invocation patterns, and parameter semantics. It gives the agent enough to understand expected response structure and when to use it, especially in context of sibling meta-tools.

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

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

The schema covers the single optional `topic` parameter with a list of values, and schema description coverage is 100%. The description reinforces parameter meaning with examples ('finance', 'pharma', 'betting') and explicitly explains the behavior when omitted (full spread), adding value beyond the schema.

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

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

The description clearly states the tool's role as the onboarding entry point, lists example user queries, and explains it returns category-bucketed example questions with exact tool and argument mappings. It distinguishes itself from siblings by explicitly naming meta-tools and positioning itself as the first thing to use.

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 this FIRST when you do not yet know what Pipeworx can do for you.' It also names alternative tools (ask_pipeworx, entity_profile, compare_entities) to learn how to call them, providing clear context on when this tool is appropriate versus alternatives.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description discloses that ownership is enforced and that the row is deactivated rather than deleted, preserving historical events. This adds significant behavioral context.

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

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

Two sentences, no fluff. The action is front-loaded and each sentence provides essential information about cancellation, ownership, and the soft-delete behavior.

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

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

For a single-parameter tool with annotations and no output schema, the description covers purpose, ownership, side effects, and connection to recent_alerts. It is sufficiently complete for correct invocation.

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

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

The schema already describes the id parameter as a subscription uuid from subscribe. The description simply refers to 'by id' without adding further parameter semantics. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the tool cancels a subscription by ID, using a specific verb and resource. It distinguishes from siblings like subscribe and list_subscriptions, and adds ownership and deactivation details.

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 clear context on ownership enforcement and the deactivation behavior, implying when it should be used (for canceling one's own subscriptions). However, it does not explicitly name alternatives or exclusions, so it falls 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?

Even with readOnlyHint=true and other annotations, the description adds critical behavioral context beyond them: it explains the meaning of the verdict 'could_not_verify' (not evidence, must not be shown as one) and the distinction between 'could_not_verify' and 'unsupported'. It also reveals the two-path pipeline (structured vs. grounded) and that it returns a value with citation and reasoning. This is substantial transparency.

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

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

The description is lengthy but well-structured: it opens with trigger phrases, states the core purpose, differentiates the two verification paths, lists output components, and highlights an important caveat with a bolded 'IMPORTANT' callout. Every section serves a purpose, though some redundancy exists between 'natural-language claim verification' and 'check whether something a user said is factually correct'.

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

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

Given the tool's complexity (two complex parameter types, no output schema, multiple possible verdicts), the description is thorough: it specifies when to use, the internal routing logic, the exact verdict list, and the semantics of ambiguous verdicts. This fully equips an agent to decide when to call it and how to interpret the result, making it nearly complete.

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

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

The input schema alone describes both parameters with clear descriptions and examples (100% coverage). The description does mention 'exact percent-delta math' and tolerance concepts indirectly, but it does not add any new parameter-level semantics beyond what the schema already provides. Baseline of 3 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 identifies the tool as a claim-verification tool with specific verb phrases ('verify the claim that...', 'fact check') and resource ('natural-language claim verification against authoritative sources'). It explicitly differentiates from sibling tools by outlining the fast path for financial claims and the grounded pipeline for other claims, and it even notes it replaces 4–6 sequential calls. This makes the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and clarifies the routing between financial and non-financial claims. However, it does not name any alternative tools or explicitly state when not to use this tool, so it lacks the exclusionary guidance needed for a 5.

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