Citybikes

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds meaningful context beyond annotations: cost implications ('you pay Anthropic directly'), the free default model, and the exact return structure. This enriches the behavioral profile 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, each earning its place: purpose, model options/cost, and return shape. Front-loaded with the core function; no filler or repetition.

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

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

For a 4-param tool with no output schema, the description is complete. It specifies the return format (per-model object + combined view), covers all parameters implicitly, and adds useful cost/behavioral context. The schema handles parameter details, so nothing critical is missing.

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

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

Schema description coverage is 100%, so baseline 3 applies. The description does not add meaning beyond what the schema already provides for each parameter; it simply mirrors the default model and optional key behavior already documented in the schema.

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

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

The description states a specific verb/resource: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' It clearly distinguishes itself from siblings like scan_competitor_ai_presence by focusing on general visibility scoring rather than competitor-specific analysis.

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

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

The description gives clear use contexts ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection (default workers-ai, optional anthropic with BYO key). It doesn't name explicit alternatives like scan_competitor_ai_presence, but the use cases are sufficient.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral context: it routes to 5,564 tools, fills arguments automatically, returns stable citation URIs, works on every tier, and is a single fast call. It also discloses handling of news/breaking-news queries. 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?

Although lengthy, every sentence earns its place: it leads with the 'PREFER OVER WEB SEARCH' directive, explains the routing mechanism, lists trigger phrases, provides examples, asserts default status, and names alternatives. The structure is logical and front-loaded, with no filler or redundancy.

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

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

For a complex router tool with no output schema, the description is remarkably complete. It covers purpose, usage triggers, return format (structured answer with citation URIs), tier availability, and explicit distinctions from related tools, leaving no significant gaps.

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

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

The schema already provides 100% coverage for all parameters (aliases for 'question'), so the baseline is 3. The description adds value by giving concrete example queries ('current US unemployment rate', 'Apple's latest 10-K') that illustrate the expected input format and scope, moving it slightly above baseline.

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

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

The description clearly and specifically states what the tool does: it routes questions to one of 5,564 tools across 1,462 verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It distinguishes itself from siblings by positioning as the default entry point and explicitly naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly instructs to 'PREFER OVER WEB SEARCH' and provides concrete trigger phrases ('what is', 'look up', 'find') and examples. It also gives clear 'step up only when needed' guidance for alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (all positive/safe). The description adds meaningful context beyond these: it explains the beta status, that no candidate is currently active (so the behavior matches stable), and that it is a full working router with no fallback. No contradiction with annotations. It could have added more detail about potential variations, but given the annotations cover safety, this is adequate.

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

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

The description is one paragraph of four sentences, front-loaded with the core purpose, then explains current behavior, usage, and clarifies it is not a fallback. Each sentence adds necessary information for a beta tool. It is not overly verbose and earns its place, though slightly longer than ideal.

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

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

The tool is a complex router with no output schema, but the description explains its beta nature, current equality to stable, and that it is a full router. It mentions the same response shape as ask_pipeworx, which is sufficient given the stable tool is a sibling. It does not explain potential behavioral differences when a candidate is active, but it states that explicitly ('enabled live whenever one is under test'), which is enough. Overall, complete for the audience.

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%—all parameters (question and its aliases) are described in the schema itself. The description does not mention parameters at all, so it adds no extra semantic value. The baseline for high coverage is 3, and that is appropriate here.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router, and explicitly states it is identical to the stable version currently. It distinguishes itself from sibling tools (ask_pipeworx, ask_pipeworx_grounded) by calling out it is the 'experimental edge' with candidate routing improvements. The verb+resource ('Ask Pipeworx Beta') is specific and the scope is clear.

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

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

The description explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains context—results are compared against the stable router—and clarifies it is a full working router, not a fallback stub. However, it does not explicitly mention when *not* to use it (e.g., if you want the tested/stable version instead), but this is strongly implied by the beta nature. This 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=true and destructiveHint=false, but the description adds crucial behavioral context beyond these: it discloses the extraction constraint ('using ONLY what the tool result contains'), the exact return shape including refusal_reason, and the list of possible refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). This goes well beyond the safety profile provided by annotations, making the agent fully aware of what to expect.

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 longer but every sentence serves a distinct purpose: it states the core value proposition, explains routing, details the output contract, gives usage criteria, and notes the cost difference. It is front-loaded with 'Hallucination-resistant answer mode' and organized logically. There is no redundant or filler content.

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

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

Given that there is no output schema, the description fully compensates by explicitly documenting the return structure on both success and refusal paths. It also covers comparison with the sibling tool, cost implications, and ideal use cases. For a tool with a single required question parameter and strong annotations, this description is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with all six parameters (question plus aliases q, text, input, query, prompt) described in the input schema. The description does not add parameter-specific guidance beyond the schema, as it focuses on tool behavior and output. Per the calibration baseline for high schema coverage, a 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 is a 'hallucination-resistant answer mode for high-stakes reads' and explains the mechanism: it routes through the same pipeline as ask_pipeworx, selects tools, fetches data, and extracts answers only from the tool result. It explicitly distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior, making its unique purpose unmistakable.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also notes the cost tradeoff ('Costs one extra LLM call'), giving the agent a clear decision rule between this tool and its sibling.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond these by disclosing blocking behavior for low-confidence matches and closed markets, suppression of analysis fields for safety, wide-spread tradeability flags, resolution-rule risk parsing, and news fallback retry semantics. This is rich behavioral context that annotations alone do not provide.

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

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

Though long, the description is structured into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). Every section provides actionable instructions or caveats essential for correct invocation and interpretation. Front-loaded purpose and use cases make it efficient to scan.

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

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

With no output schema, the description compensates thoroughly by detailing response shapes (market, analysis, evidence), resolver contract fields (market_match_confidence, alternatives, suggestions), parent_event behavior, news fallback fields, and safety short-circuits. It also covers edge cases like closed markets, wide spreads, and cancellation rules. This is a complete operational guide for a complex tool.

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

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

The input schema already covers all three parameters at 100% with descriptions. The tool description adds value by giving concrete examples for the 'market' parameter (slug, URL, question text), clarifying the 'depth' enum categories, and explaining the size implications of 'include_raw' (under 20KB vs 50KB-500KB). This goes beyond schema definitions but does not radically expand on them.

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

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

The description opens with a clear, specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explains the resolution/classification/fan-out pipeline and the returned evidence packet, distinguishing it from sibling tools like polymarket_edges and validate_claim. The level of detail makes the tool's purpose unmistakable.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples per bet type. However, it does not mention when not to use it or point to specific sibling alternatives, so it lacks 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses concrete behavioral details: results are sorted by distance, include specific fields, and the fallback behavior when no network is within radius_km (returns count:0 plus a note naming the nearest network). This exceeds what annotations alone convey.

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

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

The description is front-loaded with the core purpose, includes a compact list of return fields, gives a fallback detail, provides a cross-reference to a sibling tool, and ends with a concrete example. Every sentence serves a purpose and the length is appropriate 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?

With no output schema, the description fully specifies the return shape (sorted networks, fields, count:0 + note) and provides operational context (radius caveat, example output). It also tells the user the next step (get_network) for live data, making it self-sufficient for the 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%, so baseline is 3. The description adds value by clarifying output implications (distance_km, count:0 fallback), the practical radius default context ('bike networks are sparse'), and the relationship between parameters and results. It does not introduce syntax conflicts.

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, specific verb+resource statement ('Find bike-share networks near a lat/lon') and provides natural-language query examples. It distinguishes itself from sibling tools like get_network and list_networks by focusing on location-based proximity search.

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

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

The description clearly implies when to use this tool (when you have coordinates and want nearby networks) and explicitly names the alternative for follow-up: 'call get_network with its id' for live stations. It does not enumerate all sibling exclusions, but the context is unambiguous.

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

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

While annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds significant context: it specifies the data sources (SEC EDGAR/XBRL, FAERS), how off-calendar fiscal years are handled, sorting by primary metric, and that it returns paired data with citation URIs. This goes well beyond the annotations and helps the agent understand side effects and output characteristics.

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

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

The description is dense but every sentence earns its place: trigger phrases, preference guidance, type-specific behavior, sorting detail, and efficiency note. It is front-loaded with the most important info (one-call comparison, prefer over sequential) and structured from general to specific. Length is justified given the tool's complexity.

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

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

Given the tool has no output schema, the description adequately covers return behavior: sorted results, paired data, citation URIs, and what metrics are returned for each entity type. It also addresses edge cases (off-calendar fiscal years) and efficiency gains. Combined with the rich annotations and schema, the description provides a complete picture for an agent to invoke this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents the two parameters. The description enriches this by explaining what 'type' values mean in terms of data pulled (latest 10-K metrics vs FAERS/trial counts) and clarifies the 'values' format with examples. This adds domain-specific meaning beyond the bare schema descriptions, but still relies partially on the schema for structure.

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 side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides specific example queries and distinguishes itself from sibling tools like entity_profile by explicitly recommending this tool over sequential single-entity lookups.

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

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

The description includes explicit guidance on when to use the tool, including trigger phrases like 'compare X and Y' and 'rank these companies'. It also states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', naming the alternative approach and providing clear usage context. It covers both entity types with details on what metrics are pulled for each.

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

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

The description discloses far more than the annotations: required sign-in/paid tier, latency (15-60s/up to ~90s), explicit gaps[] for unanswered facets, contradictions[] scan, hop field, fetchable citation_uri only when available, and semantic excerpting of large records. No statement contradicts the readOnlyHint, idempotentHint, or destructiveHint annotations; the openWorldHint is supported by fetched_at and external source references.

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

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

The description is long but information-dense; nearly every clause carries operational constraints (account requirement, NOT open-web, gap recovery, citation_uri, latency). It front-loads the most decision-critical warning about account access and fallback. It could be reorganized into bullets for easier scanning, but the density is justified given the tool's complexity.

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

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

There is no output schema, so the description appropriately carries the return-value burden: it explains the findings packet (verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation), gaps[], contradictions[], hop field, and citation_uri semantics. Combined with latency and depth behavior, this gives an agent a complete mental model for invoking and interpreting the tool.

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

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

Schema coverage is 100% (question and depth), so the baseline is 3. The description adds meaning beyond the schema by explaining that 'question' tolerates broad/multi-part natural-language input and by tying 'depth' choices to plan gating, parallel facet counts, gap-recovery hops, and contradictions[] scans. This extra context helps an agent select parameters more effectively than the schema alone.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, with an explicit 'this is NOT open-web search' boundary. It uses a specific verb ('research'), explains the decomposition-and-routing mechanism, and differentiates itself from sibling tools like ask_pipeworx, making the purpose unmistakable.

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

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

It gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples, and directly says 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also covers account-based fallback ('If you are not signed in, use ask_pipeworx instead') and depth-specific behaviors, so an agent can confidently choose between 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 provide readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds useful behavioral context: returns top-N tools with full input schemas and curated examples, ready to call directly without a second lookup. This goes beyond annotations and helps the agent understand what to expect.

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

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

The description is three sentences and front-loaded with the core purpose. The domain list is long but valuable for an agent to gauge applicability. Each sentence adds important information: what it does, what it returns, and when to call it first. It could be slightly more concise, but it is not padded.

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

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

Given the tool's complexity (metadata discovery with many aliases and no output schema), the description is complete: it states the purpose, use cases, domains covered, and return format (top-N, full schemas, ready to call). It does not mention limit default (covered in schema) or error handling, but these are not essential for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with aliases (q, task, search, description) clearly documented as aliases for the main 'query' param. The description reinforces the query parameter with examples (e.g., 'analyze housing market trends'), but does not add semantic value beyond what the schema already provides. The baseline 3 applies 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 uses a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools by focusing on tool discovery rather than data operations, and explicitly lists domains (SEC, FDA, FRED, etc.) that it covers.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This clearly indicates it as a precursor to other tools, making the alternative context obvious.

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

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

Beyond the readOnly/idempotent annotations, the description discloses useful behavior: it is a single parallel call, returns specific fields with ordering, soft-fails on the USPTO PatentsView API sunset, and uses GDELT→GNews fallback. This adds meaningful context not present in annotations.

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

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

The description is long but information-dense, front-loaded with user-phrase examples and a clear directive. While longer than ideal, each sentence adds value for a complex multi-source tool, and the structure logically walks through purpose, behavior, returns, and usage constraints.

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

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

Given there is no output schema, the description fully specifies what the tool returns (cik, recent_filings with URIs, fundamentals with sorting, patents, news, LEI) and notes failure modes. This is complete for the tool's complexity and enables an agent to set expectations correctly.

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

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

The schema already provides 100% coverage of both parameters with examples and the limitation about names (e.g., value: 'Ticker (e.g., "AAPL") or zero-padded CIK (e.g., "0000320193"). Names not supported'). The description essentially repeats this information without adding new semantic meaning, 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 clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and returns. It distinguishes itself from siblings by explicitly saying to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and by noting the fallback to resolve_entity for names.

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

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

It gives explicit when-to-use guidance: use for holistic company profiles and prefer over chaining individual lookups. It also provides an exclusion: 'names not supported (use resolve_entity first if you only have a name),' naming the alternative tool. This is clear and actionable.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows it's a destructive but idempotent operation. The description adds context about what gets destroyed (memory key) and the intent (clearing stale/sensitive data), which goes 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?

Three concise sentences front-load the action, then provide usage context and complementary tools. Every sentence adds value with no redundancy.

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

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

For a simple single-parameter deletion tool with rich annotations, the description covers what it does, when to use it, and how it relates to siblings. No output schema needed; annotations cover safety. Complete for the tool's complexity.

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

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

Schema covers 100% of parameters with the description 'Memory key to delete'. The tool description only repeats 'by key' without adding extra syntax or format details, 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?

Description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly distinguishing it from siblings like remember and recall. It's immediately obvious what the tool does.

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

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

Explicitly states when to use ('when context is stale, the task is done, or you want to clear sensitive data') and names complementary tools ('Pair with remember and recall'), giving the agent clear guidance on tool selection.

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

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

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds process transparency by explaining the fetch-extract-emit workflow and the output format. This goes beyond annotations but doesn't disclose potential edge cases such as handling large pages or timeouts, though it's adequate.

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

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

The description is reasonably concise, with each sentence contributing to understanding. The 'Useful for' section somewhat repeats the purpose but adds client-oriented usage examples. Overall, it's well-structured and not overly verbose.

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

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

For a tool with only two parameters and no output schema, the description is comprehensive: it explains the process, output format, and practical use cases. The note about the output being a text blob ready for site-root placement covers return value adequately.

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?

Both parameters (url and max_links) are fully described in the input schema with 100% coverage. The description does not add parameter-specific semantics beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It specifies the process (fetches, extracts, emits) and the output format, distinguishing it from sibling tools like ai_visibility_check which focus on checking AI visibility rather than generating files.

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

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

The description includes a 'Useful for' section listing concrete scenarios (getting client sites indexed, drafting for own project, auditing competitors). However, it does not explicitly mention when to avoid this tool or provide alternatives, so it falls short of a 5.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds useful behavioral context by specifying what is returned (station locations, available bikes, empty slots), which goes beyond the annotation flags without contradicting them.

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

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

The description is a single, focused sentence that states the action and outcome. No filler or repetition, making it appropriately concise 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?

For a simple one-parameter tool with rich annotations and an output schema, the description fully covers the purpose and return contents. No critical information is missing, and the tool's behavior is sufficiently clear for an agent to use it correctly.

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

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

The schema already provides full parameter documentation with examples and coverage at 100%. The description only echoes the same example ("citi-bike-nyc") without adding additional meaning, so it meets the baseline but adds little beyond the schema.

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

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

Clearly states the tool checks live bike availability at stations for a specific network, with a concrete example ("citi-bike-nyc"). This distinguishes it from sibling tools like list_networks or search_networks, which manage networks rather than station-level availability.

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

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

The description implies the tool is for when you have a specific network id in mind, saying "in a specific network." It does not explicitly mention alternatives or when not to use it, but the context is clear enough for a simple lookup tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds value by specifying exactly what fields are returned (name, ID, city, country, coordinates) and the worldwide scope, going 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 a single, front-loaded sentence that states the action and deliverables without any fluff or repetition. It earns its place completely.

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, no-parameter list tool with rich annotations and an output schema, the description fully covers what the tool does and what it returns. There is no missing information needed for an agent to select and invoke it 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 tool has zero parameters and the schema is empty with 100% coverage. The baseline is 4 because there are no input parameters to explain. The description doesn't need to address parameters and focuses on the output, which 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 ('Browse') and resource ('all bike-sharing networks worldwide'), clearly distinguishing it from sibling tools like get_network, search_networks, and citybikes_networks_near by emphasizing the global, unfiltered 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 phrase 'all bike-sharing networks worldwide' makes the intended use clear: when you need a comprehensive list of networks without location or search filters. It doesn't explicitly mention alternatives, but the context strongly implies this is the broad, unfiltered access point.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds valuable behavioral context by specifying it returns the caller's own subscriptions only ('caller's active') and enumerates the response fields, which is beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the core action, and every sentence earns its place. The first sentence states purpose and return fields; the second gives usage context. No wasted words, perfectly sized.

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, the description provides complete context: what it lists, what fields are returned, and when to use it. The schema covers the parameter, annotations cover safety, and the description covers the return format and usage scenarios. No gaps.

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

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

The schema provides 100% coverage with a clear description for the include_inactive parameter. The tool description does not explicitly mention this parameter, but it implicitly references active subscriptions. Since the schema fully documents the parameter, the baseline of 3 is appropriate; the description adds no extra parameter semantics.

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

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

The description uses the specific verb 'List' and clearly identifies the resource as 'the caller's active subscriptions.' It also lists the exact fields returned, making the tool's purpose unambiguous and distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit guidance on when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly connects to related actions (subscribe/unsubscribe) and gives clear use cases, effectively guiding the agent.

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, leaving the description to carry the burden. It discloses the token-based read flow ('Filing without an account returns a claim_token'), rate limits ('Rate-limited to 5 per identifier per day'), async processing ('digests daily'), and non-quota impact. No contradiction with annotations; readOnlyHint=false aligns with the write nature.

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

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

The description is longer than average but every sentence carries weight. It is front-loaded with the purpose, then flows into usage, exclusions, token mechanics, and constraints. It could be tightened (e.g., 'Free; doesn't count against your tool-call quota' is nice but not essential), but the structure is logical and not redundant.

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 and no required parameters, the description fully covers both usage modes (new feedback and claim_token retrieval), the exact scenarios, the boundary conditions (only Pipeworx tools), and rate limits. The team reads digests daily setting expectations for response time. Nothing critical 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?

Input schema has 100% parameter descriptions, so baseline is 3. The description adds practical value beyond the schema: it shows the exact claim_token round-trip example, advises not to paste the end-user prompt, and explains the context object in terms of Pipeworx packs/tools. This is a slight but meaningful uplift.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly distinguishes this feedback tool from sibling research/query tools by focusing on issues with Pipeworx tools themselves, and names the relevant siblings (other MCP servers) as out of 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?

Provides explicit when-to-use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear when-not-to-use with an alternative: 'if the tool came from a different MCP server... file it with that server instead.' This is model guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: data is self-aggregated from CF analytics-engine, contains no PII, includes only (pack, tool, count), and is cached for 5 minutes to 1 hour depending on window. This discloses provenance, privacy, and caching behavior 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 approximately 100 words with a clear structure: it opens with the core purpose, lists the returned data, presents three specific use cases, and finishes with data provenance and caching details. Every sentence adds value and there is no redundancy or filler.

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

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

For a simple one-parameter read-only tool with no output schema, the description adequately covers the input (window), the output (top tools, packs, call volume), and data composition (pack, tool, count). It could be slightly more complete by specifying the exact response format or any pagination, but it is sufficient for practical use.

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 a detailed description of the 'window' parameter, covering the enum values and the tradeoff between shorter and longer windows. The tool description reinforces the window values and adds a minor note about cache duration varying by window, but this is more behavioral than semantic and does not significantly enhance understanding of the parameter beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume from other agents on Pipeworx, with a specific verb ('Returns') and resource ('what other AI agents are calling'). It also provides three concrete use cases that differentiate it from sibling tools like discover_tools by focusing on current aggregate usage patterns.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and checking alignment with common agent needs. It gives clear context on when to use the tool, but does not explicitly name alternatives or provide when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the base safety profile is covered. The description adds substantial behavioral context: how partition checks work, the 3pp threshold, placeholder filters, Jaccard similarity requirements, and fill check against live CLOB depth. It explains what happens in each mode and what outputs to expect, going well beyond annotations.

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

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

The description is long but appropriately detailed for the tool's complexity, covering three modes, edge cases, and output structure. It is front-loaded with the core purpose and then systematically explains each mode. Slight redundancy exists (e.g., repeating 'partition_check' concept), but overall every sentence contributes. Could be even tighter with structured lists, but effective as is.

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

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

With no output schema, the description fully explains return values: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers edge cases like skipped_low_similarity, placeholder filtering, and the fill check's realizable_edge_pp. Despite lacking a formal output schema, the description provides a complete picture of behavior and 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 schema already gives 100% coverage for both 'event' and 'topic' parameters with clear descriptions. The tool description further enhances semantics by providing concrete examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explaining the exact behavior each parameter triggers, and noting accepted URL formats. This adds significant value beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools by specifying the exact method and offering different scanning modes (trending, event, topic), making its purpose instantly recognizable and distinct.

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: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also directs users to an alternative tool for custom sizing ('use polymarket_fill_risk') and warns when not to trade ('do not trade it' if fill check shows non-realizable edge). This is comprehensive and actionable.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial context: it details output structure (by_segment, fed_candidates, _diagnostics), explains design trade-offs (partition arbs return kelly_fraction_half=0 by design), discloses limitations (Fed signal unreliable without paid data), and notes caching behavior ('Cached 1h at KV level keyed on all knobs'). This is far beyond what annotations provide.

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

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

The description is long but dense, front-loading the core purpose in the first sentence. Every sentence adds useful detail, but the lack of paragraph breaks or bullet points makes it a wall of text. For a tool with 9 parameters and a complex output, the length is justified, though structure could be improved.

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

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

With no output schema, the description fully explains the response shape: 'EVERY OPPORTUNITY carries edge_pp_net...', 'RESPONSE TOP-LEVEL: by_segment{...}', and '_diagnostics{...}' so callers understand what to expect. It also covers caching, model families, and filters, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description groups some knobs (e.g., 'TRADEABLE-EDGE KNOBS') and explains the interaction between min_kelly and min_partition_leg_kelly, but most parameter meaning is already captured in the input schema. This provides marginal added value over the structured fields.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's goal ('what should I bet on today') and differentiates from siblings like polymarket_arbitrage by focusing on edge opportunities from Pipeworx data rather than arbitrage.

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

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

The description explicitly states when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It gives clear context on the intended use case and even explains what the tool does NOT do (excludes Fed bets from ranking due to unreliable signal). However, it does not explicitly name alternatives 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?

Beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true), the description adds rich behavioral detail: snapshots written on cache-miss, 60-day TTL, decay computed on daily closes, gaps meaning no scan, and response semantics (tracked vs expired vs snapshot_dates). This far exceeds what annotations alone provide.

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

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

The description is long but well-structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence contributes meaningful information about purpose, output, or limitations, so it earns its length despite being 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?

With no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and provides interpretation guidance (e.g., median lifespan as a 'competition clock'). It also covers edge cases like snapshot gaps and TTL limitations, making the tool self-contained.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value by introducing the concept of 'snapshot family' for 'window' and clarifying that 'days' is a lookback with default and max values, which complements the schema's technical 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, descriptive verb phrase: 'Edge persistence and decay telemetry' and states the exact question it answers ('how long has this edge existed and is it shrinking?'). This clearly distinguishes it from siblings like polymarket_edges (which likely lists current edges) and polymarket_arbitrage by focusing on historical persistence and decay.

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 compare fresh vs. old edges and infer that an old wide edge is 'wide for a reason nobody is willing to take.' It does not explicitly name alternatives like 'use polymarket_edges for current snapshots,' but the framing makes the use case clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description adds rich behavioral context by detailing the order-book walk, return fields, and risk warnings about partial fills converting an arb into an unhedged directional position. 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 long but exceptionally dense and well-organized: it front-loads the core purpose, then clearly delineates single-market and basket modes, their parameters and return values, and ends with actionable usage guidance. No filler or redundancy; every sentence adds necessary information for correct tool use.

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 two-mode tool with no output schema, the description comprehensively enumerates expected return fields, parameter semantics, mode selection, and failure modes. It covers what an output schema would otherwise provide, plus practical risk context that prevents misuse.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema: size_usd interpretation differs between single-market (max spend/target proceeds) and basket (settlement notional S), side defaults per mode, and the mutual exclusivity of market vs event parameters. This goes well beyond the schema's field descriptions.

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

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

The description opens with a highly specific verb phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and clearly distinguishes single-market vs basket modes. It explicitly differentiates itself from sibling tools by stating it should be used before polymarket_arbitrage or polymarket_edges trades.

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

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

It provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to choose single-market mode vs basket mode and what inputs each requires, leaving no ambiguity.

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 and idempotent behavior. The description goes far beyond by explaining compatibility_warning semantics, temporal_alignment implications, and the skipped_cross_type/subtype counters. This gives the agent a thorough understanding of edge cases and reliability of the output.

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

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

Although long, the description is well-structured and front-loaded with the purpose. It uses clear segmentation (modes, response, safety fields) and every sentence contributes operational detail without redundancy. This level of detail is justified given the tool's complexity and lack 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?

With no output schema, the description must explain return values, and it does thoroughly: leg-by-leg prices, matched spread top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. It also covers limitations (pre-mapped ≠ tradeable) and current behavior, making it self-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?

The schema has 100% coverage but describes each parameter tersely. The description adds essential semantics: 'topic' is a pre-mapped shortcut, 'kalshi_event_ticker' and 'polymarket_event_slug' override the topic mapping, and it clarifies that either topic or explicit pairings must be used—an interaction not evident from the optional parameters alone.

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

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

The description clearly states the tool's purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the two modes (topic shortcuts and explicit ticker/slug) and the response structure, distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The description provides clear usage context: when to use topic shortcuts vs. explicit pairings, and it explains when spreads are meaningful (equivalent bet shapes, temporal alignment) and when they are not (compatibility_warning, aligned:false). It also warns that most pre-mapped topics return warnings, but it does not explicitly name alternative tools as a when-not-to-use guidance.

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

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

Annotations already declare the tool as read-only, non-destructive, and idempotent. The description adds valuable context beyond this: the scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the behavior of listing all keys when the key is omitted. 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 compact and front-loaded with the core functionality. Each sentence earns its place: core function, use case, scoping, and sibling relationship. No wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the two modes, the scoping, and the relationship to remember/forget. It doesn't specify error behavior for a missing key or the exact list format, but those are minor gaps given the low complexity.

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

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

The schema already covers the key parameter, including its meaning and that omitting it lists all keys (100% coverage). The description enriches this with concrete examples of key types (ticker, address, notes) and clarifies the scoping semantics, adding value beyond the schema.

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

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

The description clearly states what the tool does: retrieve a value saved via remember, or list all saved keys when the key argument is omitted. It distinguishes the tool from siblings by explicitly mentioning remember and forget as its companion tools, and provides concrete examples of stored context (target ticker, address, notes).

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 says to use this tool to look up context the agent stored earlier, avoiding re-derivation from scratch. It also tells how to pair with remember to save and forget to delete. However, it doesn't explicitly state when not to use it (e.g., if the value is already in the current context), so it's clear but not exhaustive.

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

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

The annotations declare readOnlyHint=true, but the description states that setting mark_read:true will 'flag returned events read so the next call only shows newer ones.' This is a state-modifying behavior, directly contradicting the read-only annotation. No other behavioral context is provided to mitigate this.

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 with no redundancy. It front-loads the core purpose, then provides filtering, mark_read behavior, and an alternative endpoint, all in a compact, scannable format.

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

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

Despite no output schema, the description covers return fields, filtering parameters, the mark_read side effect, and an alternative access method. It is functionally complete for an alerts-retrieval tool, aside from the annotation contradiction which is already penalized.

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 has 100% coverage, and the description adds value by giving a concrete example for type ('sec_8k') and clarifying the effect of mark_read on subsequent calls. It also explains the return payload fields (source, citation_uri, raw event), which adds semantic context beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' which clearly states the tool's verb and resource. It differentiates from siblings like list_subscriptions and recent_changes by specifying it retrieves alert events, not subscriptions or generic changes.

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 concrete usage context: filtering by type ('sec_8k') and since (ISO timestamp), using mark_read to advance the feed cursor, and notes that 'Polls work fine.' It also offers an alternative HTTP endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds significant behavioral context: fans out to multiple sources (SEC EDGAR, GDELT, GNews fallback, USPTO), notes rate-limiting fallback behavior, and mentions a soft-fail for the patent API. It does not elaborate on error handling or edge cases, but the added context is valuable.

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

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

The description is long but densely packed. It front-loads user intent examples and then covers sources, parameter formats, return structure, and alternatives. Every sentence provides useful information; however, the initial list of example phrases could be shortened without loss.

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

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

With no output schema, the description compensates by explaining the return structure (changes[] grouped by source, total_changes count, citation URIs). It also covers the fan-out behavior, fallback logic, and the `since` format. The description is complete for the tool's complexity and provides sufficient context for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic detail beyond the schema, such as concrete examples for `since` ('7d', '30d', '3m', '1y'), the recommendation to use '30d' or '1m' for monitoring, and clarification that `value` accepts tickers or zero-padded CIKs, which slightly overlaps with schema but reinforces understanding.

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

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

The description clearly states the tool's function: 'change feed for a company in the last N days/weeks/months' with examples of natural language queries. It distinguishes itself from the sibling 'entity_profile' by explicitly noting when to use that 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?

The description provides explicit usage context with example queries and specifies the `since` parameter format. It gives an explicit alternative: 'Use entity_profile instead when you want the static profile...' and even recommends typical values ('Use "30d" or "1m" for typical monitoring').

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

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

The description enriches the structured annotations with valuable behavioral details: this is a key-value store scoped by the agent's identifier, authenticated users get persistent memory, and anonymous sessions have a 24-hour retention. This goes beyond the mere hints (readOnly=false, idempotent=true) and clearly explains the data lifecycle.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, the second gives usage context, and the third explains scoping and retention. Every clause earns its place, and there is no redundant phrasing.

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?

This is a simple tool with two string parameters, annotations, and no output schema. The description covers purpose, when to use, storage semantics, and companion tools, providing everything an agent needs to select and invoke it correctly. No important information is missing.

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

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

The input schema already fully documents both parameters (key and value) with examples and types (100% coverage). The description adds no additional parameter-specific semantics, so it neither degrades nor improves on the schema. A baseline score of 3 is appropriate given the high schema coverage.

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

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

The description uses a specific verb ('Save') and names the resource ('data the agent will need to reuse later'), making the tool's function immediately clear. It also distinguishes itself from sibling tools by explicitly mentioning recall and forget for retrieval/deletion, ensuring no ambiguity about what 'remember' does.

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

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

The description provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference') and states the benefit ('so you don't have to look it up again'). It refers to companion tools, but does not explicitly state when not to use it, though the context strongly implies it is for durable, reusable information.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, establishing a safe, non-destructive profile. The description adds rich behavioral detail: internal cascading through multiple lookup endpoints, graceful degradation if GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers, and source labeling. This goes well beyond what annotations provide and equips the agent to understand the tool's full behavior 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 detailed but well-structured, starting with example queries and then breaking down supported types and behavior. While longer than average, every sentence adds important detail about the tool's multi-source resolution and error handling. The structure is logical and front-loaded with key usage cues, justifying the length for a non-trivial tool.

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

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

The tool has no output schema, so the description carries the full burden of explaining return values. It adequately describes the identifiers returned (CIK, ticker, LEI, FIGI, RxCUI) and the special handling of unresolved entries. The explanation of the cascading lookup and grace degradation provides a complete mental model for the agent. A slight improvement would be a hint about the expected JSON structure, but it is sufficient for reliable invocation.

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

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

Schema coverage is 100% with both parameters described. The description adds value by clarifying what types of values are accepted (e.g., ticker, CIK, ISIN, or name for company) and explains the ISIN-to-LEI mapping for non-US entities. It also provides concrete examples like 'ozempic' or 'metformin'. This adds meaning beyond the schema's enum and string 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 that the tool resolves user-spoken names to canonical/official identifiers needed as input by other tools. It provides example queries and lists supported entity types. While it implicitly distinguishes from sibling tools like entity_profile (which likely needs an ID already), it could be more explicit about the exact boundary between this tool and other lookup or comparison tools.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving a clear when-to-use instruction. It also describes what each entity type resolves to and notes graceful degradation. However, it does not explicitly state when not to use the tool or name alternatives, though the context of sibling tools provides some implicit guidance.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds meaningful behavioral context by explaining that it probes each entity via ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the safety profile and clarifies the operational mechanism.

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

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

The description is two sentences long, front-loaded with the core action and includes a concrete use case, example query, and output specification. Every sentence adds value with no redundancy.

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

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

The tool has no output schema, but the description explicitly states the return values (ranked list with score, confidence, signal density). The schema covers all parameters and the annotations cover safety. The description sufficiently explains the method and use case, though it omits potential rate limits or cost implications of probing multiple entities.

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% description coverage for all four parameters, including detailed descriptions for models, _apiKey, context, and entities. The description does not add further parameter semantics beyond what the schema already states (e.g., first entity as 'subject'), 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 states a specific action ('Compare AI visibility across multiple entities side-by-side') with clear scope (your brand + N competitors) and outcome (ranks by score, surfaces most/least recognized). It distinguishes itself from sibling ai_visibility_check by focusing on multi-entity comparison and explicitly referencing it as the internal probing mechanism.

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

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

The description gives a clear use case ('competitive AI-marketing audits') and an example query, providing strong contextual guidance. It implicitly suggests ai_visibility_check as the single-entity alternative but does not explicitly name it as an alternative or state when not to use this tool, so it falls short of full explicit guidance.

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

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

Annotations already declare read-only and idempotent behavior, but the description adds substantial context: fans out across multiple services, returns a specific summary block with enumerated fields, and discloses partial failure/degradation behavior including latency (5-30s) and the sources_failed field. This goes well beyond the structured annotations.

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

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

The description is front-loaded with the core purpose and then systematically covers sources, usage, return fields, scope limit, and failure behavior. It is slightly long but every sentence carries information—no filler. The use of dashes and lists within a single paragraph makes it scannable, though a touch more structure (e.g. separate sentences for each concern) could improve readability.

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 of a composite tool with two external data sources and no output schema, the description is remarkably complete. It details the returned summary fields, per-advisory detail, links, alternative versions, ecosystem limitations, and graceful degradation on partial failures. Agents will know exactly what to expect and how to handle edge cases.

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

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

The input schema already fully describes both parameters (package name with scoped package support, version with default-to-latest). The description adds little new parameter-specific meaning beyond what the schema 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 clearly states a specific composite check ('should I add this npm package to my project') and names the exact sources (deps.dev, bundlephobia). It distinguishes itself by saying 'in ONE call' and explicitly noting the NPM-only scope, differentiating from other tools.

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

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

Provides explicit trigger phrases ('is X safe / popular / small', 'what does adding lodash cost me') and clear exclusion criteria ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'). This gives agents concrete when-to-use and when-not-to-use guidance.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds that it 'Returns matching networks with their locations and IDs,' which provides some return context, but it does not disclose potential behaviors such as result limits, pagination, or empty-result 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?

The description is concise, with two sentences. The first sentence front-loads the primary purpose, and the second adds return information. There is no fluff 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 tool's simplicity (one required parameter), the rich annotations, and the presence of an output schema, the description is sufficiently complete. It conveys the core functionality and the nature of the results, though it might explicitly note that it only searches by text name and not by proximity. Overall, the context is adequate for correct selection and invocation.

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

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

The input schema provides 100% coverage for the query parameter, including a clear description and examples. The tool description only reinforces that the search is by city or country name, adding no new semantic details beyond what the schema already states.

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

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

The description uses a specific verb and resource: 'Find bike-sharing networks by city or country name.' It clearly defines the tool's scope, and the search-by-name aspect distinguishes it from siblings like list_networks and get_network, though without explicitly naming them.

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

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

The description offers no guidance on when to use this tool instead of alternatives such as list_networks or get_network. There is no mention of prerequisites, exclusions, or the intended scenario beyond the basic action, leaving the agent without clearer usage context.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description goes beyond these by disclosing the embedding model (BGE-base-en), similarity scoring (cosine), windowing (500-char overlapping windows), input cap (200K chars), and truncation behavior (longer inputs are truncated and flagged). These details give the agent an accurate mental model of the tool's behavior without contradicting any annotation.

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

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

The description is three sentences, each earning its place: purpose, usage guidance, and technical behavior. It front-loads the core action and uses capitalization/dashes for emphasis. No fluff, all high-signal content.

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

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

Given the tool's moderate complexity, no output schema, and rich annotations, the description fully covers what the tool does, when to use it, how it behaves, what parameters mean, and what the return looks like (offsets and similarity scores). It also addresses edge cases (truncation) and integration with a sibling tool. This is a complete and self-sufficient description.

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 enriches this by explaining the intended use of 'text' (passed from a fetched record, e.g., SEC 10-K body, article), clarifying that 'query' is natural-language with concrete examples, and specifying that 'limit' controls top-N passages. This adds practical meaning beyond the schema's field descriptions.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes this tool from siblings by emphasizing that it operates on already-fetched text rather than external sources, and it names the output (top-N passages with offsets and scores). This is unambiguous and well-differentiated.

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

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

The description explicitly states when to use the tool ('when the record is too big to cram into the prompt'), explains the benefit ('saves context, returns only the passages that matter'), and directly names an alternative/sibling ('Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document'). This provides clear and actionable usage guidance with an explicit alternative.

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

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

The description discloses many behavioral details beyond the annotations: always-on feed, optional delivery channels, phone verification and daily cap, webhook signing secret returned once, and auto-disable after 10 consecutive failures. This is rich, valuable 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 dense but well-structured: it front-loads the core action, then systematically covers types and delivery. Every clause contributes unique operational information without unnecessary fluff.

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

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

It covers all essential aspects for invocation: prerequisites, return value, per-type parameters, delivery options, security details, and failure behavior. With no output schema, the description adequately bridges the gap.

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

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

Despite 100% schema coverage, the description adds concrete examples for each subscription type (sec_8k items, polymarket_edge topic, fred_series series_id, etc.) and delivery constraints (E.164 phone, HTTPS webhook, HMAC signing). This far exceeds the schema's generic 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 'Create a proactive monitoring subscription to a live-data event stream,' clearly specifying the verb, resource, and return value. It is easy to distinguish from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly states the OAuth account requirement and that anonymous/BYO accounts cannot persist subscriptions, which is a key usage constraint. It also explains the supported subscription types, but it does not directly contrast with sibling tools (e.g., list_subscriptions), though the distinction is 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it returns dynamically generated examples from a live catalog of thousands of tools, and it can focus by topic. This helps the agent understand the open-world, catalog-driven nature of the response 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 front-loaded with user query phrasings, then explains the return type and parameter usage. It is longer than strictly necessary due to the list of query variants, but each part serves to disambiguate user intent and convey the tool's scope. It is structured enough to read as a cohesive onboarding guide.

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 sufficiently explains what the tool returns: category-bucketed example questions with exact tool and argument shape. It also covers the only parameter and provides strong context about its place in the tool ecosystem. The description is complete for an onboarding tool with simple schema and rich annotations.

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

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

The input schema provides 100% coverage for the single optional 'topic' parameter, including exact allowed values and default behavior. The description echoes these examples ('finance', 'pharma', 'betting') and adds the concept of a cross-category spread, but this is largely redundant with the schema. Since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool and argument shape. It uses specific verbs like 'Returns' and explicitly distinguishes itself from sibling tools by positioning it as the 'FIRST' step and referencing meta-tools like ask_pipeworx and entity_profile.

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

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

The description explicitly states when to use: '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 and with-topic usage patterns. It does not explicitly name alternative tools or when not to use, but the guidance is clear and context-rich.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavioral details: ownership enforcement, soft-delete (deactivated not deleted), and the side effect that historical events remain available via recent_alerts. This enriches understanding of the tool's side effects.

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

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

Two sentences, front-loaded with the primary action. Every sentence contributes essential information (action, ownership, soft-delete behavior, and link to recent_alerts). 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?

With a single parameter, no output schema, and informative annotations, the description covers all necessary operational context: how to cancel, restrictions, and post-effects. It is complete for the tool's complexity.

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

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

The input schema already provides complete description for the single parameter ('Subscription id (uuid) returned by subscribe'), with 100% coverage. The description only repeats 'by id' without adding new syntax or format details, so it doesn't elevate beyond the schema baseline.

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

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

The description clearly states the action ('Cancel a subscription') and the resource ('by id'), which is specific and unambiguous. It distinguishes itself from sibling tools like subscribe (opposite operation) and list_subscriptions (listing) by focusing on cancellation.

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: ownership is enforced (only your own subscriptions), and the deactivation behavior is explained. It implicitly guides when to use this tool (to stop alerts) and references recent_alerts for historical events, though it doesn't explicitly compare with 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 mark it read-only, open-world, idempotent, and non-destructive. The description adds crucial behavioral details beyond that: it distinguishes could_not_verify (check didn't happen, must not be shown as evidence) from unsupported (no source covers it), explains the structured vs. grounded routing, and notes it returns verdict, actual value, citation, and reasoning. This goes well beyond the annotation hints.

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

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

The description is long but information-dense; it packs trigger phrases, purpose, internal paths, return values, error semantics, and an efficiency note into a single paragraph. It's structured with semicolons and dashes for readability. While not as terse as possible, every sentence earns its place given the tool's nuances.

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 schema covers both parameters and no output schema exists, the description nonetheless enumerates the six possible verdict values, explains the meaning of the two ambiguous ones (could_not_verify, unsupported), and hints at the comparison math (exact percent-delta). It also positions the tool as replacing a multi-step pipeline, giving the agent a full picture of what to expect.

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

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

Schema already documents both parameters with examples (e.g., 'Apple's FY2024 revenue was $400 billion') and the 0.5–50 range for tolerance_pct. The description adds semantic value by explaining that tolerance_pct overrides the claim-implied tolerance, recommends 1–2% for hallucination detection, and notes a default cap of 5%. For 'claim', the description reinforces the natural-language nature but doesn't add new facts.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases ('fact check', 'verify the claim that…') and the statement 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates the financial-claims fast path from the general grounded pipeline, and notes it replaces 4–6 sequential calls, distinguishing it from 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?

The description gives an explicit usage directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two internal pathways for financial vs. other claims, which implies the appropriate context. However, it does not explicitly name alternatives or state when not to use the tool, so it stops short of full-guidance.

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