Ban Fr

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower. The description adds valuable context: the default model is free (Workers AI Llama-3.3-70b), and passing _apiKey incurs direct Anthropic charges, which is an important cost disclosure. It also states the return format (per-model score, confidence, signals, raw_response) 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?

Three sentences, front-loaded with the core purpose, followed by optional key behavior and return format. No filler or redundant restatement of the tool name; every sentence contributes essential information.

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

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

Despite no output schema, the description covers the return value structure (per-model score, confidence, signals, raw_response, combined view), default behavior, billing implications, and use cases. Combined with complete schema documentation and read-only annotations, an agent has all necessary context to call 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 description coverage is 100%, so baseline 3 applies. The description mostly reiterates what the schema already states (e.g., workers-ai is the free default, _apiKey enables Anthropic) without adding new parameter-level meaning beyond the property descriptions.

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

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

The description clearly states the tool probes one or more LLMs about a business/brand/product/topic and scores visibility 0-100 per model. It uses a specific verb ('probe') and resource ('LLMs'), and distinguishes itself from sibling tools like ask_pipeworx (Q&A) and scan_competitor_ai_presence (competitor-specific) by focusing on generic visibility scoring.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the default model vs. passing _apiKey for Anthropic. It does not explicitly name alternatIVes or list when not to use it, 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 provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds useful behavioral context: it routes to one of 5,596 tools, fills arguments, and returns structured answers with stable citation URIs. It does not mention rate limits or failure modes, but these are less necessary given the rich annotation set.

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?

It is front-loaded with the key signal—'PREFER OVER WEB SEARCH'—and most sentences carry purpose. However, the long domain list and examples make it somewhat bloated, and the trailing note about breaking news is folded awkwardly into the description. It is useful, but not as clean or scannable as it could be.

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

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

For a broad, read-only question tool, the description is almost complete: it explains the scope, the preferred use cases, when to use a different tool, and the type of answer. The main gap is not addressing the similarly named siblings ask_pipeworx_beta and ask_pipeworx_grounded, which leaves minor routing ambiguity.

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

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

The schema covers the question parameter and aliases at 100% coverage, so the baseline is 3. The description adds real value by giving examples and specifying the kinds of questions that are valid: factual, current or historical, real-world entities, or numeric. This helps the agent understand the intent and scope of the single natural-language parameter.

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

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

The description clearly states what the tool does: it routes a natural-language question to one of 5,596 tools across 1465 verified sources and returns a structured answer with pipeworx:// citation URIs. It also distinguishes itself from web search and names deep_research as a sibling alternative for broad fan-out. However, it does not explain how ask_pipeworx differs from the similarly named ask_pipeworx_beta and ask_pipeworx_grounded siblings.

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

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

Start with the explicit 'PREFER OVER WEB SEARCH', then gives 'use whenever' trigger phrases and examples, plus an explicit exception: use deep_research for broad or multi-part fan-out questions. This gives the agent strong guidance about when to invoke this tool 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?

Even with annotations present, the description adds meaningful behavioral context: it is the experimental edge, candidate routing improvements may be live, the last candidate was retired, and it 'falls back to nothing' because it is a full working router. 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 well front-loaded with the identity and shared scope, and each sentence earns its place. The repeated phrasing around 'same tools, same arguments, same response shape' is slightly verbose but helps clarity.

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

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

For a complex router with no output schema, the description gives strong context: the stable router relationship, current inactive candidate, comparison behavior, and non-fallback status. It does not describe the response shape in detail, but 'same response shape' being from ask_pipeworx keeps it usable.

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

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

The input schema already documents all six parameters and aliases at 100% coverage. The description mostly confirms 'same arguments' but does not add new semantic detail beyond what the schema already provides, 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 identifies the tool as a beta universal router in the ask_pipeworx family, with specific details like 'same 5,596 tools, same arguments, same response shape'. It also distinguishes itself from the stable ask_pipeworx by emphasizing candidate routing improvements and its experimental edge.

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

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

The description explicitly says 'use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. However, it does not explicitly say to prefer ask_pipeworx when experimental candidate routing is wanted, so the when-not guidance is slightly implicit.

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, idempotentHint), the description discloses the exact behavioral contract: it uses only the tool result content, returns an explicit refusal with a structured reason, and incurs an extra LLM call. This adds material context and does not contradict 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?

Every sentence earns its place: outcome, mechanics, return shape, refusal behavior, use cases, and cost tradeoff are all conveyed in a dense, front-loaded structure without filler.

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

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

With no output schema, the description still fully describes the output structure and refusal reasons. Combined with the complete input schema and explicit usage context, there is no missing essential information 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?

Schema description coverage is 100%, with each parameter fully documented. The description does not add new parameter detail, so the schema carries the full responsibility; 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 states a specific verb and resource: a hallucination-resistant answer mode that extracts the answer strictly from the tool result. It also contrasts itself with ask_pipeworx by saying 'Same routing as ask_pipeworx' and then adds the grounded extraction behavior, making the differentiation clear.

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

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

Explicitly says when to use this mode—whenever an answer will be quoted, cited, or acted on and must not be invented—and when not to use it, by stating 'prefer ask_pipeworx for casual lookups.' This directly addresses sibling routing decisions.

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?

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, the description adds extensive behavioral detail: resolver contract fields, fan-out examples per classifier, safety short-circuits ('low_confidence_match', 'market_closed_or_inactive'), wide-spread market flags, cancellation rule parsing, and news fallback behavior. This goes well beyond the annotations and gives a complete picture of how the tool behaves in edge cases.

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

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

The description is long but well-structured, using clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loading the core purpose in the first sentence. Each section covers a distinct aspect of behavior, so it earns its place. It could be trimmed slightly, but the organization keeps it navigable and information-dense.

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

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

Given the tool's complexity and lack of an output schema, the description is exceptionally complete. It details response shapes (market, analysis, evidence), resolver contract fields (market_match_confidence, market_match_score, alternatives, suggestions), parent-event extraction, news fallback fields, and multiple blocking/edge-case statuses (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread). It also covers resolution-rule risk and safety measures, leaving no significant gap for an agent to misuse 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 100% coverage with detailed descriptions for all parameters (market, depth, include_raw). The description repeats the market input formats but adds no additional parameter-specific semantics beyond what the schema states. Thus, the baseline of 3 for high schema coverage applies; the description does not meaningfully compensate 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 clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), the action (research/pull data), and differentiates from siblings by emphasizing a one-call evidence packet plus market-vs-model comparison. The explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') further solidify its purpose.

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

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

The description provides clear usage context with explicit use-case phrases: 'Use for ...' and examples. It also describes input formats (slug, URL, question text). However, it does not explicitly mention when not to use this tool or name alternative sibling tools like polymarket_edges or polymarket_arbitrage, earning a 4 rather than a 5.

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

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

Annotations already indicate read-only, non-destructive behavior. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in results. This goes well beyond annotation basics, though it doesn't mention potential errors or rate limits.

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

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

The description is dense but each sentence earns its place—trigger phrases, explicit preference guidance, data source details, and result format. It could be broken into bullets for scannability, but it's appropriately sized for the tool's complexity and delivers high information density.

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 only 2 parameters and full schema coverage, the description is quite complete: it covers usage, data sources, sorting behavior, and return format (paired data + citation URIs). It lacks caveats about edge cases (e.g., invalid tickers) but for a read-only comparison tool with clear schema, it's sufficient.

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 parameter meaning by explaining the semantics of each type ('company' pulls financials, 'drug' pulls adverse-event/trial counts) and providing concrete examples for values. This adds practical guidance beyond the schema's field descriptions.

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

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

The description clearly states the tool's function: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It gives concrete trigger phrases and distinguishes it from sequential single-pack lookups, making it unambiguous and distinct from siblings like entity_profile.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains the two entity types and what data each pulls, clarifying appropriate contexts for company vs drug comparisons.

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 readOnly/openWorld/idempotent hints: it details a multi-step decomposition-and-routing process, parallel tool execution, output packet structure (evidence, confidence, source, fetched_at, citation_uri), explicit gaps[] behavior, contradictions[], hop semantics, semantically excerpted records, response-time expectations, and account/plan restrictions. It even clarifies that citations are present only when fetchable. Nothing contradicts the annotations; rather, this transparently explains what the operation does despite being read-only and idempotent.

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 frontloads critical prerequisites and alternatives and fills every later sentence with concrete operational facts (parallelism, citation behavior, gap handling, timing, truncation behavior). It repeats the ask_pipeworx guidance twice, which is minor redundancy, but the length is proportioned to the tool's real complexity and the absence of an output schema.

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 is complex (decomposition research, multiple depth modes, fallbacks, citations, gap handling) and has no output schema, the description fully covers invocation, prerequisites, return-values structure, quirk edge cases, timing expectations, and alternative routing. An agent selecting this tool knows what input to supply, what output to expect, and which situations are unsuitable.

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

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

The input schema already describes both parameters at 100% coverage, and the description adds a useful layer beyond the schema: it explains the practical effect of depth values in context (standard re-angles gaps, thorough chases leads and costs extra, quick acts in a single hop), and relates the depth choice to waiting times. It also confirms the question parameter is meant for natural-language, multi-part questions. This is more than a restatement of the schema, hence above the baseline 3.

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

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

The description states a specific action: "Grounded multi-source research" across a catalog of 1465 structured data sources, and disambiguates it immediately from open-web search and from ask_pipeworx. It explains the tool decomposes questions, routes facets to parallel tools, and returns a findings packet. This is a clear, resource-specific purpose that an agent can distinguish 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?

Explicit when/when-not guidance is present: "Best for broad/multi-part questions over structured data" and "For a single lookup use ask_pipeworx instead." It also gives an authentication-based switch: "If you are not signed in, use ask_pipeworx instead" and names the depth plans and access tier needed for thorough. The agent is told exactly when to select this tool over a known 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the return payload: top-N tools with names, descriptions, and full input schemas, including curated examples, and that results are 'ready to call directly, no second schema lookup needed'. This gives a complete behavioral contract 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?

Three sentences, front-loaded with the core action, then usage guidance, then return format. No filler; every sentence contributes a distinct piece of 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?

With no output schema, the description takes on the responsibility of explaining return values, and does so thoroughly: top-N, fields (names, descriptions, full schemas with examples), and readiness for direct invocation. It also states when to call first, making the tool fully self-contained 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?

Input schema covers 100% of parameters, so the baseline is 3. The description adds value by explaining that the output is top-N (directly informing the `limit` parameter) and that results include full schemas, hinting at the rich output. The `query` parameter's flexibility is reinforced by the topic list, but no additional syntax details are provided beyond the schema's own aliases and examples.

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 'Find tools by describing the data or task', a specific verb+resource statement that clearly distinguishes this meta-tool from sibling tools like ask_pipeworx or deep_research. It enumerates supported domains (SEC filings, FDA drugs, etc.), making the tool's scope concrete.

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 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance and implicitly contrasting with single-answer tools. Although no alternative tool names are given, the guidance is actionable and specific.

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?

While annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields, notes a soft-fail for USPTO sunset, describes a GDELT→GNews fallback, and limits filings to 5. This goes well beyond what annotations provide, giving the agent a clear picture of operations.

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

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

The description is long but well-structured, front-loaded with user-facing examples and then a detailed breakdown of outputs. Every sentence earns its place by describing scope, alternates, limitations, or return values. It could be slightly tightened, but it remains highly informative 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?

With no output schema, the description thoroughly enumerates the return structure (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers fallback behavior, source sunset, and parameter constraints. This is complete enough for an agent to select and invoke the tool correctly without additional context.

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

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

Schema coverage is 100% with good descriptions for type and value. The description adds value by providing concrete examples ('AAPL' or zero-padded CIK '0000320193'), reinforcing the zero-padding requirement, and explicitly restating that names are unsupported. This is meaningful enhancement over schema alone, though not exhaustive since the schema already covers the basics.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' - a specific verb+resource combination. It distinguishes itself from siblings by explicitly saying it should be preferred over chaining single-pack SEC/XBRL/news lookups for holistic views, and differentiates from resolve_entity for name resolution.

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

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

Explicit usage guidance is provided: 'ALWAYS PREFER over chaining... when the user asks for a holistic view.' It also clearly states a key exclusion: 'names not supported (use resolve_entity first if you only have a name).' This gives clear when-to-use and when-not-to-use guidance with an alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about when to use deletion (stale context, done task, sensitive data) but does not disclose additional behavioral traits like irreversibility or error handling. Since annotations cover the safety profile, a 3 is appropriate.

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 action, and zero redundancy. Every sentence earns its place.

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

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

For a simple one-parameter delete tool with strong annotations and no output schema, the description covers purpose, usage, and parameter semantics sufficiently. Might mention permanence or error behavior, but destructiveHint covers that, so it's 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?

Schema coverage is 100% with a clear parameter description ('Memory key to delete'). The description's 'by key' adds no new meaning 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 the tool's function: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory), and differentiates from siblings like remember (store) and recall (retrieve).

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 provides when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions complementary tools 'Pair with remember and recall,' which clarifies its role among alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds process details (fetches page, extracts title/description/key links) and output format (single text blob), which is useful context beyond the annotations.

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

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

The description is compact: three sentences covering what, how, and when. No fluff, each sentence earns its place, and key information is front-loaded.

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

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

The tool is simple (2 params, no output schema) and the description covers process, output format, and use cases. It lacks edge-case handling details (e.g., invalid URLs), but given the simplicity and rich annotations, it is sufficiently complete.

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

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

Schema coverage is 100% with both parameters described. The description adds no extra parameter-level details 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 uses a specific verb (generate) and resource (llms.txt file for any URL), clearly explaining what the tool produces and its purpose. It distinguishes itself from siblings by focusing on generating the file itself, not just checking or scanning AI presence.

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

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

Provides explicit use cases (client indexing, drafting own project, auditing competitor) that clarify when to use it. However, it does not mention when NOT to use it or name alternatives like ai_visibility_check, so no 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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond these: it specifies the output format (scored GeoJSON with score 0-1 and specific fields) and the geographic restriction (France only). This enriches the behavioral model without contradicting the annotations.

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

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

The description is two sentences, front-loaded with the action verb and resource, and every clause adds value. It mentions the output format and scope in a compact manner with zero 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 read-only, non-destructive geocoding tool with a rich input schema, the description covers the main purpose, geographic scope, and output shape (scored GeoJSON, fields included). Since there is no output schema, describing the return format is essential and handled well. It could mention errors or rate limits, but those are less critical for this simple read operation.

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

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

The input schema has 100% parameter description coverage, with each parameter having a detailed description. The tool description adds no additional parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Forward-geocode a French address, street, locality or commune.' This uses a specific verb with a specific resource type and geospatial scope. It distinguishes itself from the sibling 'reverse_geocode' by explicitly using the term 'Forward-geocode' and adding 'France only'.

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 when to use the tool (for forward geocoding) and provides clear context (France only, returns scored GeoJSON matches). It does not explicitly mention alternatives or when-not-to-use, but the contrast with 'reverse_geocode' is strongly implied. The parameter descriptions also offer usage hints (e.g., bias with lat/lon), which adds guidance beyond the main description.

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 destructiveHint=false, so the safety profile is covered. The description adds value by stating the return fields, scoping to the caller's subscriptions, and the default of active only. This goes beyond the structured data and provides useful behavioral context without contradiction.

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

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

The description is concise, consisting of three short sentences that front-load the purpose, list return fields, and give usage guidance. There is no redundancy or unnecessary detail. Every sentence contributes value, making it highly efficient.

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

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

For a simple list tool with one optional parameter and rich annotations, the description provides sufficient context: it states what is returned, the scope (caller's active subscriptions), and appropriate use cases. The absence of an output schema is mitigated by listing return fields. It lacks only minor details like pagination, but these are not apparent necessities here.

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

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

Schema description coverage is 100% for the only parameter (include_inactive), and the schema already explains it. The description does not add extra meaning about the parameter, but it does indirectly clarify that 'active' is the default by saying 'active subscriptions.' Baseline 3 is appropriate since the schema handles the parameter documentation.

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 pair. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing, and it specifies the return fields (id, type, params, etc.).

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implicitly references alternatives (subscribe/unsubscribe) but does not explicitly name them or state when not to use the tool. Strong but not maximally explicit.

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

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

Annotations are all false, so the description carries the full burden and delivers richly: it discloses the claim_token workflow for follow-up, rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and that the team reads digests daily. 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 longer than average but every sentence adds value: usage criteria, exclusions, claim_token flow, rate limits. It is front-loaded with the main purpose. Slight verbosity in explaining the 'different MCP server' exclusion, but overall well-organized.

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 no-output-schema tool with zero required params, the description covers all necessary context: what to report, how to scope feedback to Pipeworx tools, follow-up via claim_token, rate limits, and impact on roadmap. It is complete for effective invocation and interpretation.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond schema: it explains the claim_token format and usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), clarifies the type categories, and instructs users not to paste the end-user prompt. This goes beyond baseline parameter descriptions.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly scopes the tool to feedback for Pipeworx services and distinguishes it from sibling tools by stating 'ONLY for tools served by this Pipeworx connection' and contrasting with other MCP servers.

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

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

Explicit when-to-use guidance is given: bug, feature/data_gap, or praise. It also states when NOT to use (tools from other MCP servers) and provides a fallback check ('Not sure? Pipeworx tool names are the ones this connection lists.'). 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?

The description goes well beyond the provided annotations, revealing that the data is self-aggregating, derived from CF analytics-engine, contains no PII (just pack, tool, count), and is cached 5min-1h depending on window. These are concrete behavioral details not present in the annotations.

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

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

The description is front-loaded with the core purpose, and the use-case list provides value. It is slightly verbose with the three enumerated use cases, but each sentence earns its place. It could be tightened, but it's well-structured and readable.

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

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

For a simple single-param tool with no output schema, the description fully covers the return shape (top tools, top packs, total call volume, and the (pack, tool, count) tuple), the available windows, privacy, and caching. No essential context is missing.

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

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

The schema already fully describes the `window` parameter with enum values and an explanation of tradeoffs between short and long windows. The description adds a brief mention of the windows and cache timing but doesn't materially extend the schema's parameter semantics, so it stays at baseline 3.

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

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

The description opens with a clear question-and-answer format: 'What other AI agents are calling on Pipeworx right now.' It then lists the exact outputs (top tools, top packs, total call volume) and the time windows. This is a specific verb+resource+scope that clearly distinguishes it from siblings like discover_tools.

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

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

The description provides three explicit use cases, including discovering hot data sources, confirming canonical tool choice, and aligning with agent needs. It does not explicitly name alternative tools or state when not to use it, so it stops short of the full 5-level guidance.

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

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

Even though annotations already declare readOnly/idempotent/non-destructive, the description adds rich behavioral context: the fill-check mechanism, the partition filter dropping placeholder slugs, the >3pp threshold for signals, and the warning that realizable_edge_pp <= 0 means do not trade. This goes far beyond the annotations and sets accurate expectations for output and edge cases.

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

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

The description is long but every sentence delivers unique value: modes, semantic anchor, partition filter, response fields, fill check, and pointer to sibling tool. It is front-loaded with the core purpose and structured with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). No filler or redundancy.

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

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

Given the complexity (two modes, edge cases, output format, integration with other tools) and the lack of an output schema, the description covers every necessary aspect: response field names, threshold semantics, failure modes (null arb signal), and how to interpret fill-check results. It is self-contained and leaves nothing critical unexplained.

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 parameters 100%, but the tool description adds critical semantics: the difference between event (single-event mode, specific slug) and topic (cross-event mode, seed question), plus the 'top ~200 markets' behavior when both are omitted. This transforms the parameters from simple strings into meaningful mode selectors.

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 distinguishes three modes (no args, event, topic) and identifies the tool's unique niche among siblings by naming the fill-risk tool as a companion. This is far clearer than typical tool descriptions.

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: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also explicitly points to an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This is textbook 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?

Annotations declare readOnly/idempotent/non-destructive, and the description adds extensive behavioral detail beyond that: caching behavior ('Cached 1h at the KV level'), model family specifics (e.g., lognormal barrier, GDELT ratio), Kelly capping at 0.25, placeholder-slug filtering, partition-level Kelly behavior, and a 24h-move warning. It also explains why Fed bets are unreliable. 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 lengthy but highly structured with clear sections (model families, knobs, response top-level, caching). Every sentence conveys useful information, but the sheer density might overwhelm some agents. It is appropriately detailed for the tool's complexity, but not maximally concise; a more compact summary could improve scannability.

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

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

With no output schema and a complex response (three segments, diagnostics, nested fields), the description fully covers the return structure, including how to interpret empty segments, the role of diagnostics, and the Fed candidates note. It also explains the three opportunity types in detail, making the tool's behavior transparent even without structured output definitions. It is complete for an agent to invoke and interpret results.

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

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

The input schema already provides 100% coverage with detailed descriptions for all 9 parameters, so the baseline is 3. The description adds extra meaning by explaining how parameters interact, e.g., min_partition_leg_kelly applies to per-leg Kelly inside top_legs because parent-level kelly_fraction_half is always 0 for partition arbs, and min_kelly filters single-leg opportunities only. It also clarifies the semantics of slippage_pp and tradeable-edge filters. This goes beyond simple schema repetition.

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 verb+resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further specifies the intended use case ('what should I bet on today') and differentiates from siblings by focusing on Pipeworx disagreement rather than pure arbitrage or tracking. The tool's unique value proposition is explicit.

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

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

The description states when to use it: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It also provides guidance on knobs to adjust (min_liquidity/max_spread_pp) and a notable exclusion: Fed bets are excluded from ranking because the signal is unreliable. However, it does not explicitly name alternative sibling tools or say 'use this instead of X', so it falls just short of perfect.

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

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

The description extensively discloses behavioral traits beyond annotations: response structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL, snapshot gaps due to cache-miss), and computation details (decay based on daily closes of edge_pp_net, not intraday). This adds significant value beyond the readOnlyHint and idempotentHint 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 well-structured, front-loaded with the core purpose, followed by parameter details, response breakdown, and limitations. Each section uses clear formatting (e.g., uppercase field names) and provides necessary information. It could be slightly more concise, but it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity, no output schema, and minimal parameters, the description is thoroughly complete. It explains the return structure (tracked, expired, snapshot_dates), what each element means, and critical limitations (TTL, snapshot gaps, calculation basis). This fully equips an agent to understand what the tool will return and its constraints.

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

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

Schema coverage is 100% with descriptive parameter definitions. The description adds minimal extra meaning: it restates defaults (days default 14, window default '1wk') and adds max 30, but the schema already includes these details. Since the schema already does the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question: 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges by focusing on historical tracking rather than current edge values.

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

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

The description provides clear context for when to use the tool: to evaluate edge persistence and decay before trading, with the example contrasting fresh vs. old edges. It does not explicitly exclude alternatives, but the purpose is well-scoped. No explicit alternatives are mentioned, but the use-case is evident from the description.

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, idempotent, and non-destructive. The description goes well beyond by detailing how it walks the order-book ladder, what metrics it returns (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about 'partial basket fills convert an arb into an unhedged directional position' — a key behavioral risk not evident from annotations alone.

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

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

Despite its length, the description is tightly organized with clear sections (SINGLE-MARKET vs BASKET), leading with a crisp purpose statement. Every sentence earns its place, providing necessary detail for a complex two-mode tool 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 must explain return values, and it does so thoroughly for both modes, including page-level details like thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also covers usage context, risk warnings, and alternative tools, making it complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100% and already describes each parameter well. The description adds value by clarifying the one-of relationship between market and event, explaining the auto default for side in basket mode, and how size_usd is interpreted differently per mode (max spend/target proceeds vs settlement notional). However, much of this repeats schema details, so it doesn't fully exceed the baseline.

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

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

The description opens with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes single-market vs basket modes. It also explicitly contrasts with siblings by naming polymarket_arbitrage and polymarket_edges, making the tool's unique role 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?

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely on theoretical overround, mentioning the risk of partial fills, which effectively sets boundaries for 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 description goes far beyond annotations by explaining compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type counters. This adds substantial behavioral context that annotations alone do not provide, and it does not contradict the readOnly/idempotent hints.

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

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

The description is long but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Some sentences could be tightened, but the thoroughness is justified for a complex tool.

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

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

With no output schema, the description correctly explains return values, including spread structure and safety fields. It covers the complexity well, though it omits error-handling examples and a full sample response, leaving some edge cases unaddressed.

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 all three parameters, but the description adds meaning by explaining the mode-based interaction (topic auto-fetch vs explicit overrides) and the purpose of the safety fields. This goes beyond the schema's property 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource pairing. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or compare_entities, so it stops short of full clarity.

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

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

The description clearly explains two usage modes (topic shortcuts vs explicit ticker/slug) and warns that pre-mapped topics often return compatibility warnings. It does not reference alternative tools, but it provides strong contextual guidance for when to use this tool and what to expect.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds scoping context ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual-mode behavior of retrieving versus listing. It does not mention error handling or return format, but these are minor gaps beyond the annotation baseline.

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

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

Three well-structured sentences with no filler. The primary action is front-loaded, followed by usage context, scoping, and pairing with siblings. Every sentence adds value without redundancy.

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

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

The description covers purpose, usage, scoping, and relationships with related tools. Since there is no output schema, it could have explicitly stated what is returned (e.g., the saved value or list of keys), though the phrase 'list all saved keys' implies this. Missing error behavior (e.g., if key is not found) is a minor gap for an otherwise simple 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 schema already provides 100% coverage for the single 'key' parameter, including the note to omit it to list all keys. The description adds examples of key values (ticker, address, notes), which provides some semantic color, but does not significantly increase understanding beyond the schema's own description.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs and resources, and explicitly distinguishes from sibling tools by mentioning remember and forget. The examples of use cases (target ticker, address, research notes) further clarify purpose.

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

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

The description provides explicit usage guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives and complements: 'Pair with remember to save, forget to delete.' This clearly indicates when to use this tool versus memory-related 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?

The description adds rich behavioral detail beyond annotations: the payload structure (source, citation_uri, raw payload), the side-effect of mark_read (flags events read so next call shows newer ones), and the persisted feed nature. This is valuable context even though readOnlyHint and idempotentHint already 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 four sentences that front-load the purpose and then efficiently cover payload, filtering, and the alternative endpoint. No filler or redundancy.

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

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

For a read-oriented tool with no output schema, the description covers return payload, filtering, and side effects. It could mention the unread_only parameter or default limit, but the schema already provides those. The external endpoint and polling note add completeness.

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

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

The schema covers all 5 parameters with 100% description coverage, so baseline is 3. The description adds meaning by giving a concrete type example ('sec_8k') and explaining mark_read behavior semantically. However, it omits unread_only and limit details, which the schema already documents, so not a full 5.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns the most recent alerts, distinguishing it from sibling tools like list_subscriptions or recent_changes. The verb 'pull' and resource 'fired events' are specific.

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

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

The description provides clear usage context: filtering by type and since, setting mark_read, and notes that polling works well. It also mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools or state when not to use it.

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

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

Goes well beyond annotations by disclosing data source fan-out, rate-limit fallback (GNews when GDELT rate-limited or 5xx), USPTO soft-fail due to API sunset, and return structure (changes[] grouped by source + total_changes + pipeworx:// citation URIs). No contradiction with readOnly/idempotent hints.

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

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

Dense but efficient: front-loaded with the core purpose, then specifics. The list of example queries is slightly redundant but helps intent matching. Every sentence adds value (sources, fallback, since format, output, alternative).

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

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

Even without an output schema, the description explains return values and sources. It mentions grouped changes and citation URIs, but does not detail the fields of each change, which would be useful for a complex tool. Still, it gives enough 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?

Schema already describes all 3 parameters at 100% coverage (type, since, value). Description adds a minor recommendation ('Use "30d" or "1m" for typical monitoring') and examples, but this is additional guidance, not essential semantics. Baseline for high coverage is 3.

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

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

The description states a clear purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call' with specific sources (SEC, GDELT/GNews, USPTO). It distinguishes itself from entity_profile by explicitly naming the alternative for static profiles.

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

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

Provides explicit when-to-use examples ('What's new with X', 'latest on Y') and an explicit exclusion: 'Use entity_profile instead when you want the static profile...'. Also details fallback behavior (GDELT→GNews) to inform expected performance.

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 include idempotentHint=true and destructiveHint=false. The description adds context beyond annotations: key-value scoping by identifier, authentication-based persistence (24-hour retention for anonymous), and pairing with recall/forget. No contradiction.

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

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

Three sentences packed with purpose, usage, storage semantics, and sibling pairing. Slightly longer than minimal but every clause adds value; front-loaded with the core action.

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 2-param tool with no output schema, the description covers purpose, usage, persistence, scoping, and pairing with related tools. Complete for an agent to decide when and how to invoke.

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 both params fully with examples, but description reinforces that value accepts any text, clarifying flexibility beyond the schema. Adds meaning to the key-value concept and storage model.

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?

Specific verb 'save' + resource 'key-value pair' clearly states the tool's function. It distinguishes from siblings by explicitly mentioning recall and forget, and by describing persistent memory vs. retrieval.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' with concrete examples. Also notes persistence differences by authentication status, giving clear context for when to rely on it.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses critical behaviors: internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, and explicit reporting of unresolved identifiers under an 'unresolved' field. This fully informs the agent about failure modes and edge cases.

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

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

The description is front-loaded with examples and the 'Use FIRST' directive, then structured by entity type. While every sentence is informative, the company type section is verbose and could be slightly tightened. However, given the tool's complexity, the length is justified.

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

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

For a tool with no output schema, the description adequately conveys return content (identifiers, labels, unresolved list, graceful degradation). It covers edge cases like ISIN and non-US issuers. However, it stops short of explicitly stating the output structure format, which would improve completeness for agent parsing.

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 substantial value: for 'type' it explains the cross-source identity spine and RxNorm integration; for 'value' it clarifies acceptable inputs (ticker, CIK, ISIN, name) and unique behavior like ISIN-to-LEI mapping. This goes far beyond the schema's brief 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 explicit example queries and a clear 'resolve a user-spoken NAME to the canonical/official identifiers' statement. The 'Use FIRST whenever you have a name but need an ID' hint differentiates it from sibling tools like entity_profile and compare_entities, making purpose highly specific 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?

The description provides strong when-to-use guidance ('Use FIRST'), outlines supported input types, and states that it replaces 2-3 manual lookups. However, it does not explicitly exclude use cases or name alternatives, leaving some room for ambiguity against siblings like entity_profile.

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

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

Annotations already provide safety hints (readOnly, idempotent, non-destructive). The description adds meaningful context beyond that: it specifies the return format (scored GeoJSON matches) and the exact fields returned (label, postcode, citycode, context, distance in metres), as well as the France-only limitation. 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 two sentences, front-loaded with the primary action and scope, followed by a compact summary of the return fields. Every sentence earns its place with no redundancy or fluff.

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

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

The tool is relatively simple (3 params, no output schema). The description adequately covers the purpose, return format, and geographic constraint. It could mention that multiple matches may be returned or how they are ordered, but the main context is sufficiently covered.

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 descriptions cover 100% of parameters, including units (WGS84) and the 'type' enum. The description adds no additional param-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'reverse-geocode' combined with the resource 'coordinate' and clearly states the geographic scope ('France only'). This distinctly differentiates it from the sibling tool 'geocode' (forward geocoding) and other location tools.

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

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

The description clearly establishes the tool's context (reverse geocoding for French addresses) and geographic constraint ('France only'), but it does not explicitly name alternatives or state when not to use it. The verb itself implies the use case, so this is still 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 provide read-only, idempotent, non-destructive hints. The description adds behavioral value by revealing the probing process (calls ai_visibility_check), ranking by score, and output structure (ranked list with score, confidence, signal density). No contradiction with annotations.

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

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

Two sentences, front-loaded with the core purpose, followed by an example and return details. No filler words; 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?

Without an output schema, the description appropriately describes the return format (ranked list with score, confidence, signal density). It covers the multi-entity comparison, ranking, and use case. It could mention behavior on probe failure or score interpretation, but is complete for a read-only tool with clear annotations and schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of 'your brand + N competitors' merely restates the schema's 'first entry treated as subject.' It adds no additional meaning beyond the schema for parameters.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), resource (AI visibility), and scope (multiple entities). It distinguishes from siblings like ai_visibility_check by explicitly focusing on multi-entity comparison and ranking.

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 for when to use this tool: 'Useful for competitive AI-marketing audits' and cites an example question. It names ai_visibility_check as the underlying probe, implying single-entity checks. However, it does not explicitly state 'use this instead of X for single entities' or mention exclusions, but the contextual guidance is strong.

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=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. Description adds valuable behavior beyond annotations: composite fan-out, graceful partial failures, bundlephobia timing (5-30s), and sources_failed handling. 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?

Five dense sentences, front-loaded with the composite purpose, then use-case, return fields, ecosystem scope, and failure behavior. Each sentence adds necessary information; only minor redundancy (e.g., mentioning bundlephobia twice) prevents a 5.

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

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

With no output schema, the description enumerates all return elements (summary block fields, per-advisory detail, links, alternative versions), covers sources, ecosystem extension, timing, and error degradation. This fully compensates for missing structured return information.

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 package and version fully described including scoped package example and default for omitted version. The description adds no parameter syntax or semantics beyond what the schema provides, 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 uses a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call' and enumerates concrete sources (deps.dev, bundlephobia) and scope (npm package). It clearly distinguishes itself from sibling research tools by focusing on package evaluation.

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 provides when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also gives an exclusion/alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already declare readOnly, idempotent, and non-destructive properties, so the safety profile is covered. The description adds value by specifying the resolved data fields (INSEE code, postcode, population, coordinates), which helps the agent understand the operational behavior without being too verbose.

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 exactly two sentences: the first clearly answers 'what does this do', and the second references the alternative. There is no redundant phrasing and it is front-loaded, making it highly concise and well-structured.

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

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

The tool is simple with only two parameters and strong annotations. The description explains the output fields but does not explicitly state that the tool returns multiple results or describe the response format. Considering the absence of an output schema, a note about the list nature would improve completeness, but it is otherwise adequate.

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

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

The input schema provides full descriptions for both parameters (q and limit), achieving 100% schema coverage. The description adds the phrase 'by name' which matches q, but doesn't offer any additional semantic nuance beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('look up') and resource ('French commune'), and lists the exact output fields (INSEE citycode, postcode, population, centre coordinates). It clearly distinguishes itself from the sibling tool geocode by labeling itself as a shortcut, making the purpose unambiguous.

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

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

The description explicitly mentions it is a 'shortcut for geocode with type=municipality', giving clear context for when to use it instead of the more general geocode tool. However, it does not explicitly state when not to use it or compare with other lookup tools like reverse_geocode, so there is a minor gap.

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, so the safety profile is clear. The description goes well beyond this by disclosing the exact embedding model (BGE-base-en), window size (500-char overlapping), the 200K character cap, and truncation behavior (longer inputs are truncated and flagged), which is valuable behavioral context for the agent.

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 long but every sentence carries substantive information: the core action, the use case, the pairing, and the technical details. It is front-loaded with the main purpose and then adds distinguishing context. No sentences are filler, but it could be tightened by moving the embedding detail to a separate note.

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

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

There is no output schema, but the description clearly explains what the tool returns: top-N passages with character offsets and similarity scores. It also covers limitations (200K cap, truncation), the algorithm, and the input format. For a tool with 3 well-described parameters, this is fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema, though it does reinforce the character limit on the text parameter and provides example queries. The schema already documents each parameter well, so the description adds marginal value.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with a specific verb ('search') and resource ('inside a fetched record'). It also distinguishes itself from siblings by explicitly noting it pairs with ask_pipeworx_grounded, differentiating the workflow of searching within already-fetched text versus broader queries.

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

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

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also mentions pairing with ask_pipeworx_grounded, indicating an alternative/supplementary workflow, but does not explicitly state when not to use the tool or list other sibling alternatives for exclusion.

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

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

Annotations already indicate a non-read-only, idempotent, non-destructive operation, so little is needed on basic side effects. The description adds meaningful context: requires a Pipeworx OAuth account, anonymous/BYO cannot persist, feed is always-on, and SMS has a 10/day cap. It does not discuss webhook behavior, but that is covered in the input schema's webhook field, so the description adds sufficient value without contradiction.

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

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

The description is moderately long but well-structured, leading with the purpose, then supported types, then delivery channels. Each section is information-dense and relevant. It could be tightened by dropping the phrase 'Supported types' when it only lists three of five, but overall it is efficiently organized and front-loaded.

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

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

Given the tool's complexity (3 params, nested object, multiple subscription types and delivery channels), the description covers the core behavior, return value, auth requirements, and primary delivery modes. It omits two subscription types (patent_grant, clinical_trial) and the webhook channel from the main text, but the input schema's param and delivery descriptions fill these gaps. No output schema exists, but 'Returns the new subscription id' is enough for basic use; webhook secret details are in the schema.

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

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

Schema coverage is 100% so the baseline is 3. The description adds value with concrete examples for sec_8k (items ['5.02'] = officer change), polymarket_edge (topic:'fed'), and fred_series (series_id:'UNRATE'), and reiterates SMS verification constraints. It does not fully cover patent_grant and clinical_trial in the main description, but the schema's params description covers those, keeping this dimension above baseline.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes itself from sibling tools like recent_alerts (pull) and unsubscribe (remove), and states the primary return value (subscription id). Though it omits two schema-listed types from its examples, the core 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?

The description provides clear context on when to use the tool: creating persistent subscriptions for live-data events, with explicit account requirements (OAuth, anonymous/BYO cannot persist) and delivery options. It also hints at alternative consumption via recent_alerts or a JSON endpoint. It lacks explicit 'when not to use' or comparable sibling exclusions, but the context is clear enough.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context: results are category-bucketed, drawn from a live catalog, and each example includes the exact tool and argument shape. It also explains the effect of omitting vs. passing a topic, going beyond the annotation hints.

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

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

The description is dense but every sentence earns its place: it covers user intents, return contents, both invocation modes, and workflow placement. The structure flows naturally from example queries to purpose to operational details, and the length is appropriate for an onboarding tool.

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

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

For a low-complexity tool with one optional parameter, no output schema, and strong annotations, the description is complete. It fully explains what the tool returns, how to call it, and when to use it during an initial agent interaction. Nothing essential is missing.

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

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

The sole optional `topic` parameter is already fully documented in the schema, including the allowed values and the note to omit for a cross-category spread. The description restates these examples but adds no new semantic detail beyond the schema, so the baseline 3 applies.

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

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

Description opens with the exact user intents and immediately identifies this as the onboarding entry point for a connected agent. It then specifies concrete return content—category-bucketed example questions paired with the exact tool and argument shape—which clearly distinguishes it from sibling tools like discover_tools or ask_pipeworx.

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

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

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the no-argument vs. topic-focused invocation. However, it does not name explicit exclusions or direct users to alternatives like discover_tools for other discovery scenarios.

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

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

Beyond the annotations, the description adds valuable behavioral context: ownership enforcement and that the row is deactivated rather than deleted, preserving historical events in recent_alerts. This fully explains the write operation's side effects and aligns with the destructiveHint and idempotentHint flags.

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 primary action, and includes only necessary behavioral nuances. Every sentence earns its place, with no redundancy or 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?

For a simple one-parameter mutation tool with full schema coverage and informative annotations, the description covers the action, a key constraint (ownership), and the non-destructive side effect. It also ties to recent_alerts for follow-up. This is complete enough 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 input schema already documents the single parameter 'id' with a full description ('Subscription id (uuid) returned by subscribe'), providing 100% coverage. The description adds no additional parameter detail, so it meets the baseline of 3 without exceeding it.

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

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

The description clearly states the tool's action: 'Cancel a subscription by id.' This is a specific verb+resource pairing that distinguishes it from siblings like subscribe and list_subscriptions. The ownership enforcement note further clarifies 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?

The description gives clear context: use to cancel a subscription by id, ownership is enforced, and the effect is a deactivation rather than deletion. It doesn't explicitly mention alternatives, but the intended use is evident and no exclusions are needed.

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

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

The description adds rich behavioral context beyond the readOnly/idempotent/non-destructive annotations: it discloses the underlying pipeline routing, the percent-delta math for financial claims, and – critically – the nuanced meanings of could_not_verify and unsupported, including a warning never to treat could_not_verify as evidence either way. This prevents serious caller misuse and demonstrates deep behavioral transparency. 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 front-loaded with trigger phrases and a one-line purpose, then proceeds through use cases, routing, return values, and caller warnings in a logical order. The 'IMPORTANT for callers' block is particularly well placed and earn-worthy. Every sentence contributes unique information without redundancy, making the length justified rather than bloated.

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 takes on the full burden of explaining return values, and it does so thoroughly: it lists all verdict states, the actual value with citation, and reasoning, and explicitly defines the failure semantics of could_not_verify and unsupported. It also covers the two operational pipelines and the efficiency gain, making the tool fully understandable and safely invocable by an agent.

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

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

The schema already fully documents both parameters with examples, giving a baseline score of 3. The description adds practical guidance for tolerance_pct: the default is implied by claim wording and capped at 5, and setting it to 1–2 is recommended for hallucination detection where any material error must be refuted. This enriches the agent's understanding of how to tune the parameter beyond the raw 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 concrete trigger phrases and states 'natural-language claim verification against authoritative sources' – a specific verb+resource pairing. It further distinguishes the tool by describing two distinct routing paths (SEC EDGAR/XBRL for financial claims vs grounded pipeline for all others) and lists the exact verdict types, leaving no ambiguity about its function relative to sibling research/query tools.

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

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

The description clearly states 'Use whenever the agent needs to check whether something a user said is factually correct,' which is strong situational guidance. It also explains the sub-routing logic and notes that it replaces 4–6 sequential calls, implying when this consolidated tool is appropriate. However, it does not explicitly name alternatives or provide when-not-to-use exclusions, stopping just short of a 5.

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