Ror

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds context about the fuzzy nature of the match and the return of candidates with confidence scores, which is useful. However, it does not disclose any limitations or specifics about the matching algorithm, but the strong annotations reduce the burden on the description.

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 extremely concise, consisting of two short sentences that front-load the core purpose and outcome. There is no fluff or redundancy; every word contributes to the description's value.

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

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

Given the tool's simplicity (one parameter, output schema present) and strong annotations, the description covers the basic purpose and a hint of the return format. However, it lacks usage context, such as when to choose this tool over alternatives and what constitutes a valid affiliation string. It is adequate for a straightforward tool but not fully complete.

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

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

Schema coverage is 0%, so the description must compensate. It mentions 'affiliation-string' which implies the 'text' parameter is an affiliation string, but this is minimal and largely tautological given the tool name. It does not elaborate on input format, examples, or accepted variations, leaving the agent with little additional semantic insight.

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 verb ('match') and resource ('affiliation-string'), indicating the tool performs fuzzy matching on affiliation strings and returns candidates with confidence scores. It distinguishes itself from generic search or entity resolution tools, though it could more explicitly differentiate from sibling tools like resolve_entity.

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?

No guidance is provided on when to use this tool versus alternatives. The description only states what it does, not when it should be invoked, prerequisites, or exclusions. This is a significant gap given the array of similar 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 establish read-only, idempotent, non-destructive behavior. The description adds valuable extra context: the default model is free (Workers AI), passing _apiKey involves direct payment to Anthropic, and the return structure is disclosed. This goes beyond annotations without contradicting them.

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

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

The description is concise (three sentences), front-loaded with the primary action, and includes only necessary details: default model, cost implication, return format, and use cases. 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 tool with no output schema, this description is remarkably complete: it explains what the tool does, how to invoke it (default vs paid), what it returns (per-model score/confidence/signals/raw_response + combined view), and when it is useful. Combined with rich annotations and full schema coverage, the agent has all necessary context.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description reiterates the relationship between models and _apiKey ('pass _apiKey to also probe Anthropic') which is already in the schema. It adds minor clarity about defaults but does not significantly extend schema semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about an entity and scoring visibility 0-100 per model. It specifies the resource (business/brand/product/topic), the output shape, and the default model, making it easily distinguishable from sibling tools like ask_pipeworx or 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 provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use the tool but does not explicitly mention alternatives or when not to use it, such as compared to scan_competitor_ai_presence or ask_pipeworx. Clear context, but no exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavioral context beyond these: it routes to sub-tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and makes a single fast call. There is no contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with the key instruction ('PREFER OVER WEB SEARCH'). Every section serves a purpose: topic list, mechanism, triggers, examples, escalation paths. It is slightly verbose with the extensive example list, but this is valuable for a default entry-point tool. A 4 reflects that it is appropriately sized but not as lean as the TDQS 4.3 example.

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

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

The description fully covers the tool's role as a default router, explaining what it does, when to use it, its coverage of sources, and its output format (structured answer with pipeworx:// citation URIs). Even without an output schema, this is enough for an agent to know what to expect. It also clarifies relationships with sibling tools, making it contextually complete.

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

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

Schema coverage is 100% (all six parameters are aliases for 'question' and each has a description). The description adds example questions but does not explain the 'question' parameter semantics beyond what the schema already states. The baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states that the tool routes natural-language questions to the correct one of 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It uses a specific verb ('routes') and resource, and distinguishes itself from siblings by 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 says to prefer this over web search for factual questions and provides trigger phrases ('what is', 'look up', 'find', etc.) plus examples. It also gives explicit when-not-to-use: 'Step up only when needed' for ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions). This is clear guidance with both inclusion and exclusion criteria.

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

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

The description goes beyond the annotations by disclosing the experimental nature, the fact that no candidate is currently active, and that it behaves identically to ask_pipeworx at present. It also clarifies that it is a fully working router with no fallback. While it does not detail specific failure modes, the provided context is substantial and aligns with the readOnly/idempotent hints.

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

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

The description is moderately concise and well-structured, front-loading the key purpose and then explaining current state and usage. Each sentence earns its place, though it could be slightly trimmed without losing value. The length is justified by the need to convey beta status, exact equivalence, and experimental context.

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

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

Given the tool's complexity as a beta router with sibling variants, the description is complete. It covers the relationship to ask_pipeworx, the experimental status, the absence of active candidates, and the fact that the response shape is identical. No important aspect is left unexplained, making it self-sufficient for an agent to decide and invoke.

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

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

The input schema already provides 100% coverage with descriptions for all parameters, including aliases and the main 'question' parameter. The description adds little beyond saying 'same arguments' as ask_pipeworx, which is useful context but does not enhance the semantic understanding beyond what the schema already offers. This meets the baseline for 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 clearly identifies the tool as a beta version of ask_pipeworx with candidate routing improvements, distinguishing it from the stable ask_pipeworx sibling. It specifies the exact scope (same 5,529 tools, arguments, response shape) and current state, leaving no ambiguity about 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?

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It contrasts with the stable router by mentioning results are compared to decide merges, and implicitly advises using the stable version if you do not want experimental behavior. This gives clear usage guidance without confusion.

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, but the description adds substantial behavioral context beyond those: the mechanism of extracting only from tool results, the exact refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the extra LLM call cost, and the guarantee of verbatim evidence. This is rich, non-redundant disclosure with no contradiction.

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

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

Three sentences earn their place: purpose, mechanism/return values, and usage guidance. The description is information-dense but not bloated; it front-loads the key differentiator. No filler words or redundant repetition of obvious schema facts. It is concise for the complexity it covers.

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 formal output schema, the description enumerates the full return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also covers cost, when to use, and the routing relationship to siblings. Given the many sibling tools and high-stakes nature, this is exceptionally complete.

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

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

Schema description coverage is 100% as all six parameters are aliases for the same question field, each documented. The description does not add parameter-level detail, but it is not needed since the schema fully covers them. Baseline 3 applies because the description adds no direct parameter semantics, but the schema carries the load.

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

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

The description opens with a specific, vivid phrase: "Hallucination-resistant answer mode for high-stakes reads." It clearly distinguishes this from its sibling ask_pipeworx by explaining that it routes the same way but then extracts the answer strictly from the tool result, returning evidence and refusals. The purpose is instantly clear and 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?

Explicit usage guidance is provided: "Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts." It also gives a concrete exclusion ("prefer ask_pipeworx for casual lookups") and names the cost tradeoff (one extra LLM call). This is exactly the level of when-to-use vs. alternative guidance the dimension asks for.

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

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

The description goes far beyond the annotations by detailing fan-out behavior, classifier mapping, resolver confidence levels, fallback handling for GDELT 429s, low-confidence short-circuits, closed-market status, wide-spread flagging, and cancellation-rule risk. These are all additional behavioral traits not covered by readOnlyHint/openWorldHint/idempotentHint. No contradiction.

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

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

The description is long but extremely well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK) and front-loaded with purpose and usage. Every sentence adds a distinct, needed behavioral detail; there is 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?

With no output schema, the description fully documents return values (result.market, result.analysis, result.evidence, match confidence fields), statuses, and edge cases (closed markets, wide spreads, cancellation rules, fallback behavior). It leaves virtually no behavioral gaps and provides all necessary context for correct invocation.

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

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

Schema coverage is 100% but the description enhances every parameter: concrete examples for market (slug/URL/question), depth semantics ('quick = 2-3 evidence sources, thorough = full fan-out'), and include_raw's impact on response size and use cases. This adds significant practical meaning beyond the bare 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 first sentence states the exact function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings by focusing on Polymarket bet research with evidence fan-out and explicitly names use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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

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

Provides explicit use-case guidance ('Use for...') and strong operational instructions like 'ALWAYS inspect these before trusting the analysis block' and 'Check this before sizing...'. However, it does not name alternative tools or state when NOT to use this tool, so it falls short of a full 5.

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

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

The description enriches the read-only/idempotent annotations with specific behavioral details: it pulls 10-K financial metrics from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This goes well beyond the annotations and provides actionable expectations.

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

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

The description is dense yet efficient. It front-loads with user intent examples, then covers data sources, behavior, and output, finishing with an ROI statement ('Replaces 8–15 sequential lookups'). Every sentence adds value without redundancy.

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

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

Given the moderate complexity (2 params, no output schema), the description fully compensates by stating what is returned (paired data, citation URIs), how results are sorted, and the data source specifics. This is sufficient for an agent to invoke the tool and interpret results correctly.

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

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

The input schema already covers both parameters with descriptions, enumeration for 'type', and constraints for 'values'. The description adds some context (e.g., what metrics are pulled for each type) but does not significantly change parameter understanding. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call. It uses specific verbs like 'compare', 'rank', and 'head to head', and explicitly distinguishes itself from sequential single-pack lookups, making its purpose and scope unmistakable.

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

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

The description provides explicit example queries ('Compare X and Y', 'which is bigger/better', 'rank these companies') and specifies when this tool should be preferred over sequential lookups. It also differentiates behavior between company and drug types, offering clear usage context.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses key behaviors: requires an account, thorough depth needs a paid plan, uses structured data only (not open-web), never invents answers (gaps[]), performs gap recovery and contradiction scans, returns fetchable citation_uris, and semantically excerpts large records. It also notes expected latency (15-60s, up to 90s for thorough), giving the agent a full behavioral model.

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

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

The description is lengthy, but almost every sentence carries essential usage or behavioral details. It is front-loaded with the account requirement and the ask_pipeworx fallback, which is critical for an agent. While some redundancy exists (e.g., repeating the gap recovery mention), the overall structure is logical and information-dense, though it could be tightened by removing minor repetitions.

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 covers the return structure (findings packet, verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, citation_uri). It also covers prerequisites (account/plan), limitations (breaking news returns empty gaps), and operational behavior (parallel routing, excerpting, latency). For a tool this complex, the description is exceptionally complete.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the raw schema. For 'question', it explains that broad/multi-part natural language is fine and that decomposition is the point. For 'depth', it elaborates on each enum value's behavioral implications: quick=single hop, standard=gap recovery+contradictions, thorough=adds lead chasing, with a note about the paid plan for thorough.

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: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' that decomposes questions, routes to tools in parallel, and returns a findings packet. It explicitly distinguishes itself from the sibling ask_pipeworx by contrasting single-lookup vs. multi-facet research and structured data vs. live news, leaving no ambiguity about its purpose.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicitly names alternatives for other cases: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides a fallback if not signed in, stating 'If you are not signed in, use ask_pipeworx instead', which 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 readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral details: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This clarifies the response format and the tool's role as a self-contained discovery 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 three sentences, each earning its place: the first states the core action, the second details the output and its readiness for direct use, and the third gives usage context ('Call this FIRST'). The domain list is extensive but directly informs the user of the searchable space, 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?

The description fully covers what an agent needs: what the tool does, when to use it (including the 'first step' directive), what it returns (names, descriptions, schemas, examples), and why that is sufficient (no subsequent schema lookup). With no output schema defined, the description's explanation of the return payload is critical and well delivered. The limit parameter is documented in the schema, so nothing essential is missing.

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

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

The input schema covers all six parameters with descriptions, and the query parameter includes rich examples. The description provides only a high-level nod to query semantics ('describing the data or task') and does not explain the alias parameters (q, task, search, description) beyond what the schema already says. Since schema coverage is 100%, 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 opens with 'Find tools by describing the data or task,' a specific verb+resource pair that clearly distinguishes this tool from data-retrieval siblings like 'search' or 'get.' It further clarifies scope by listing concrete domains and emphasizes that it returns tool metadata ('what tools exist'), making its role as a meta-search over tools unambiguous.

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

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

The description explicitly states when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't name specific alternative tools to avoid, the 'first step' guidance and contrast with 'not just one answer' effectively positions it against direct data lookups.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable behavior: fans out across multiple sources (SEC EDGAR, XBRL, USPTO, GLEIF), mentions specific return fields with URI formats, indicates the USPTO PatentsView API sunset and soft-fail behavior, and describes news fallback from GDELT to GNews. No contradiction with annotations; the added detail goes well beyond the structured metadata.

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

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

The description is long but densely informative, covering examples, return structure, API caveats, and input constraints. It is front-loaded with user-intent examples and maintains a logical flow from purpose to outputs to limitations. A few redundant example phrasings could be trimmed, but the length is justified by the tool's complexity.

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

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

Given the tool's high complexity (multiple data sources, no output schema), the description thoroughly discloses what will be returned: cik, company_name, recent_filings with URIs, fundamentals fields with sorting, patents status, news fallback, and LEI. It also covers input limitations and an alternative path, making it self-sufficient for an agent to invoke correctly.

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

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

The input schema already provides 100% coverage with detailed descriptions for 'type' and 'value', including examples and name-not-supported guidance. The description reiterates these same details without adding new parameter semantics, so it earns the baseline score for 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 clearly states this tool produces a 'full cross-source profile of a US public company in ONE parallel call' and includes example user phrasings. It differentiates from sibling tools by explicitly saying to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and contrasts with resolve_entity for name-only inputs.

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 via example queries ('Tell me about X', 'research Acme', 'brief me on Tesla') and states the preferred approach over chaining single-purpose lookups. It also gives a clear exclusion: names are not supported, and directs the agent to use resolve_entity first if only a name is available.

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 destructiveHint=true and idempotentHint=true, so the deletion behavior is known. The description adds minimal extra behavioral context beyond that, such as 'previously stored' and 'clear sensitive data.' It does not disclose, for example, whether deletion is permanent or impacts related records, but the annotation coverage lowers the bar.

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-loads the action, then provides usage guidance and tool relationships. Every sentence earns its place with no redundancy or filler.

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

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

For a simple one-parameter tool with good annotations (destructive, idempotent), the description covers purpose, when to use, and related tools. No output schema is needed for a delete operation, and the combination of schema and annotations makes the tool's behavior fully understandable.

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

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

The input schema provides 100% coverage with a clear description for the single 'key' parameter: 'Memory key to delete.' The tool description adds no extra meaning about key format or behavior; the schema already carries the full burden.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' The verb 'Delete' plus the resource 'memory' precisely identifies the action, and the opening phrase distinguishes it from sibling tools like recall (which retrieves) and remember (which stores).

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

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

It explicitly lists conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also names complementary tools: 'Pair with remember and recall.' This gives the agent actionable guidance on when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds process details (fetches page, extracts title/description/key links, emits markdown) and output format. It discloses the network fetch behavior and the nature of the result without contradicting annotations, providing meaningful context beyond the safe-operation 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 efficiently structured: purpose, process, output, and use cases are each covered in a few sentences. It is slightly verbose with the 'Useful for' list, but every sentence adds value and the key information appears early.

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 a simple 2-parameter tool with rich annotations and no output schema, the description fully covers the tool's behavior, output format, and appropriate use cases. It also implicitly differentiates from the many sibling tools by focusing on llms.txt generation, making it complete for an agent to 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 description coverage is 100%, with clear descriptions for 'url' and 'max_links' (including default and max). The description adds the notion of 'key links' and the purpose of the file, but does not materially enhance understanding of the parameters beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb+resource ('Generate a production-ready llms.txt file') and clearly distinguishes from siblings by focusing on generating the standard llms.txt format. It also details the process (fetch, extract, emit) and the target output, making the tool's function unambiguous.

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

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

The description provides clear use cases ('getting a client's site indexed...', 'drafting llms.txt...', 'auditing how an AI crawler would see a competitor') which strongly implies when to use it. It does not explicitly name alternative tools or state when not to use it, but the context is sufficient for an agent to select it appropriately.

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, idempotent, and non-destructive behavior. The description adds no extra behavioral context (e.g., caching, errors), but for a simple get operation, the annotations are sufficient.

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 short sentences with no unnecessary words. The description is front-loaded and every word earns its place.

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

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

For a single-parameter, read-only tool with output schema, the description is sufficient. It lacks usage guidance, but otherwise covers the essential semantics.

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 description explains that ror_id can be either the trailing identifier or the full URL, adding crucial format information not present in the bare string schema. This fully clarifies the one parameter.

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

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

The description says 'Full ROR record,' which implies retrieval of a ROR record by identifier. It is clear in verb+resource but does not explicitly distinguish itself from sibling tools like resolve_entity or entity_profile.

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

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

No explicit guidance on when to use this tool versus alternatives. It implies usage via identifier or URL, but does not state when this is the right choice compared to search or other lookup 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by detailing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying scope ('caller's active subscriptions'), which is useful behavioral context beyond the annotations.

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

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

The description is two sentences that are front-loaded with the core purpose, followed by return fields and usage guidance. Every sentence earns its place with no redundancy or filler, making it highly concise and well-structured.

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

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

Given the tool's low complexity (one optional parameter), rich annotations covering read-only/idempotent behavior, and full schema documentation, the description is complete. It includes return field details and practical use cases, leaving no critical gaps for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the single parameter include_inactive is fully described in the schema. The description does not add additional meaning about this parameter, so the baseline of 3 is appropriate; it neither helps nor hurts beyond what the schema already provides.

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

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

The description clearly states the tool lists 'the caller's active subscriptions' with a specific verb and resource, distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the return fields, leaving no ambiguity about 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?

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' This gives clear when-to-use guidance, though it does not explicitly mention alternatives (e.g., subscribe or unsubscribe) or when not to use the tool, so it misses the full 5-level criteria.

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 (all false) provide minimal safety signals, so the description carries the transparency burden. It excels: it discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token return behavior, that the team reads digests daily, that it's free and doesn't count against quota, and that feedback should reference Pipeworx tools/packs rather than user prompts. No annotation contradiction exists.

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 readable and front-loaded with the core purpose, then logically flows through usage rules, exclusions, claim_token behavior, and constraints. It is somewhat verbose—the same 'ONLY for tools served by this Pipeworx connection' idea is repeated with the alternative-server clarification—but every sentence adds functional value. It earns a 4, slightly penalized for 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 is a feedback submission channel with no output schema, but the description fully prepares the agent: it covers triggering conditions, scope boundaries, token-based response retrieval, rate limiting, and even sustainability ('free'). The nested 'context' object and enum are documented in the schema, and the description adds the essential workflow (file -> receive token -> later check status). This is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter-level guidance: it explains the claim_token flow in depth ('pass it back later... with no other arguments'), gives concrete examples for the 'type' enum, and instructs users on what to put in 'message' ('be specific... 1-2 sentences typical'). This goes beyond the schema's field descriptions, though it doesn't add much for '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 a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact feedback types (bug, feature/data_gap, praise) and explicitly distinguishes from sibling tools by limiting scope to 'tools served by this Pipeworx connection.' This fully clarifies what the tool does and why an agent would choose it over the many research/data tools in the list.

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 for each feedback type with concrete examples ('wrong/stale data,' 'a tool you wish existed,' 'worked surprisingly well'). It also gives a clear exclusion rule: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This is exemplary usage guidance, including a heuristic for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already establish this as a safe, read-only, idempotent operation. The description adds valuable behavioral context: it is 'self-aggregating' from CF analytics-engine, strips PII, returns only (pack, tool, count), and is 'cached 5min-1h' depending on window—clarifying data freshness and privacy beyond the annotation set.

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

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

The description is compact (about 80 words) and front-loaded with the core function. Every sentence serves a purpose: the first defines the tool, the next lists use cases, and the last adds provenance/caching. No wasted words or redundant restatement of the tool name.

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, this description is remarkably complete. It covers what it returns, the meaning of the window parameter, ideal use cases, data source, privacy (no PII), and caching behavior. An agent can confidently decide when and how to call it without further clarification.

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

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

The single parameter 'window' is fully documented in the schema with enum values and a clear explanation of trade-offs. The description merely restates the window options without adding further meaning. Since schema coverage is 100%, the description doesn't need to compensate, and it correctly leaves parameter behavior to the schema.

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

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

The description opens with a specific, unique value proposition—'What other AI agents are calling on Pipeworx right now'—and clearly states it returns top tools, packs, and call volume. This distinguishes it from siblings like discover_tools and ask_pipeworx by focusing on aggregated community call 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?

Three explicit, practical use cases are listed (spotting hot data sources, confirming canonical tools, aligning with agent needs). While it doesn't directly name alternative tools to use instead, the scenarios imply when this is the right choice, and the cache/window guidance helps with selection. Just missing an explicit 'compare with X to get...' caveat.

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. The description adds substantial behavioral context: thresholds (3pp deviation, 0.30 Jaccard, 20% placeholder fraction), the fill check logic (realizable_edge_pp <= 0 means do not trade), and the null signal behavior for partitions with high placeholder fraction. It also mentions skipped_low_similarity, disclosing rejected pair counts, going well beyond the annotations.

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

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

The description is long but well-structured, using capitalized section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize details. It is front-loaded with the core purpose and usage modes. While some technical internals (like fill check specifics) might be trimmed for an AI agent, each sentence carries meaningful information for a complex tool.

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

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

With no output schema, the description fully specifies the response structure (opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check{} fields). It covers edge cases such as placeholder slugs, low similarity filtering, and fill check outcomes. The reference to polymarket_fill_risk for custom sizing rounds out the guidance, making it 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 description coverage is 100%, with both parameters already explained. The description adds significant value: it explains the no-args trending_scan, provides examples for both event and topic, details what happens in each mode (walking child markets, checking date-axis/threshold-axis ordering, partition check), and notes that full URLs are accepted for 'event'. This goes beyond schema-level 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 states a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates from sibling tools by describing the monotonicity/partition approach and explicitly referencing polymarket_fill_risk for custom sizing. The three modes (trending_scan, event, topic) further define the tool's scope.

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

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

The description provides explicit instructions: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan.' It also gives concrete examples of event slugs and topic seeds, explains when cross-event mode is beneficial, and directs to 'polymarket_fill_risk' for custom sizing, effectively covering when and when not to use the 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 read-only/idempotent, but the description adds substantial behavioral detail: 1-hour caching keyed on knobs, diagnostics funnel counters to explain empty segments, the 24h-move warning, and the rationale for excluding Fed candidates. These go 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 extremely dense and runs as a single multi-clause paragraph. It packs in formula details, model families, output structures, and diagnostics. While each sentence carries technical value, the lack of structural formatting and excessive length makes it harder to parse; it could be more concise and organized.

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

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

Despite no output schema, the description thoroughly documents the response top-level structure (by_segment, fed_candidates, _diagnostics), opportunity fields (edge_pp_net, kelly_fraction, etc.), and tradeable-edge filters. It also covers caching and diagnostic reasons, making it highly 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?

Input schema covers 100% of parameters with detailed descriptions. The description's 'TRADEABLE-EDGE KNOBS' section largely duplicates schema content (e.g., min_partition_leg_kelly semantics are already in the schema). No significant new meaning is added beyond the schema, so baseline 3 applies.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further defines the three response segments and the intended use case, clearly distinguishing this 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 explicitly states the tool is 'Built for "what should I bet on today"' and mentions agents discover opportunities 'without paging hundreds of markets.' It also provides exclusion context (Fed bets excluded due to unreliable signal). However, it does not explicitly compare to sibling alternatives like polymarket_arbitrage, so it falls short of full differentiation.

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, idempotent, and non-destructive behavior, and the description adds substantial behavioral depth: snapshot gaps mean no scan occurred, history depth is bounded by a 60-day TTL, and decay is computed from daily closes net of slippage, not intraday. These caveats materially shape interpretation and are not disclosed in annotations or schema.

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

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

The description is long but information-dense. It is front-loaded with the core purpose, then structured into Args, RESPONSE, and LIMITS sections. Every sentence contributes necessary context about response shape, data semantics, and caveats; there is no fluff 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?

With no output schema, the description carries full responsibility for explaining return values. It thoroughly describes tracked[], expired[], and snapshot_dates[], including the meaning of trend, decay_pp_per_day, lifespan_days, and the significance of gaps. It also explains the data source and computation limitations, making it complete for a telemetry tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful context by labelling 'window' as a snapshot family and clarifying that 'days' is the lookback across prior snapshots. It also ties the effective history depth to the 60-day TTL, which gives the parameter real-world bounds beyond the schema's clamp values.

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 edge persistence and decay telemetry built from daily polymarket_edges snapshots. It states the exact question it answers ('how long has this edge existed and is it shrinking?') and differentiates from the sibling polymarket_edges by focusing on time-series analysis of historical snapshots.

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 strong contextual guidance by framing the tool's decision-relevant question ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains what the response includes. It lacks explicit when-not-to-use or named alternatives, but the context makes intended usage clear.

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

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

The description adds substantial behavioral detail beyond the readOnlyHint/idempotentHint annotations: it explains the ladder-walking process, conditional parameter requirements, return payloads for both modes, and the risk of forced directional exposure on partial fills. This is rich context that the annotations neither provide nor contradict.

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

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

The description is long, but every sentence carries essential information for a complex tool. It is well-structured with SINGLE-MARKET and BASKET blocks, front-loaded with the core purpose. It could be slightly tightened, but the density is justified by the tool's complexity.

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

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

With no output schema, the description takes full responsibility for explaining return values, and it does so comprehensively for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.). It also covers edge cases like partial fills and thin legs, making the description complete for an agent to understand what the tool will provide.

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 covers 100% of parameters, the description deepens meaning: it clarifies the conditional requirement of `market` vs `event`, changes interpretation of `size_usd` for basket mode (settlement notional vs spend/proceeds), and explains `side` defaults in both modes. This goes well beyond the schema's simple property descriptions.

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

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

The description opens with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly differentiates itself from siblings by name ('polymarket_arbitrage', 'polymarket_edges'). It details two distinct modes (single-market and basket) with concrete output fields, making its purpose unambiguous.

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

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

Explicit usage guidance provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (partial fills convert arb into unhedged position), giving clear when-to-use context and implicitly distinguishing from alternative tools.

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

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

Goes far beyond the readOnlyHint annotation by detailing edge-case behaviors: compatibility_warning fires in two specific scenarios, temporal_alignment reveals whether calendar periods align, and skipped_cross_type/subtype counters show dropped comparisons. This gives the agent deep insight into how results should be interpreted, with no contradiction to annotations.

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

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

The description is dense but well-organized: starts with purpose, then modes, response structure, safety fields, and a caveat. It is longer than average, but every section provides necessary operational detail. The front-loading of the core purpose makes it scannable.

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 explaining the response format (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and interpretation caveats. It covers success and failure modes comprehensively, making the tool fully understandable without additional docs.

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

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

While the schema already covers all three parameters with descriptions, the tool description adds meaningful semantic context: the two-mode operation (topic vs explicit kalshi_event_ticker + polymarket_event_slug) and how explicit tickers override mapped ones. This clarifies parameter interplay beyond the schema's individual descriptions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly specifying the tool's function and unique resource (comparing two prediction markets). It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on cross-venue equivalence and spread calculation.

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 strong contextual guidance: explains two modes (topic vs explicit ticker), warns that 'most pre-mapped topics return compatibility_warning today,' and states 'pre-mapped ≠ tradeable.' It clearly implies when the tool is useful (equivalent bet shapes) and when it isn't, though it doesn't explicitly name sibling 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond these: scoping to 'anonymous IP, BYO key hash, or account ID' and the ability to list all keys by omitting the key argument. It doesn't fully describe return behavior, but the added context is substantial.

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

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

The description is three sentences, front-loaded with the core action, and every sentence earns its place. It covers the main action, usage context, scoping, and sibling pairing without 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains both invocation modes, scoping, and relationship to remember/forget. No critical operational detail is missing for the 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% and the schema's key description already states 'omit to list all keys'. The description adds extra meaning by clarifying that keys are those 'previously saved via remember' and providing examples like 'the user's target ticker, an address, prior research notes'. This enriches the parameter's purpose beyond the schema.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys.' This is a specific verb+resource combination that distinguishes it from sibling tools like remember (save) and forget (delete). The two operational modes (get by key, list all) are explicitly described.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the paired tools 'remember' and 'forget', making the when-to-use vs alternatives clear. This is strong guidance beyond a generic statement.

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 directly contradicts annotations: readOnlyHint=true while mark_read:true explicitly flags events as read, a state mutation that affects future calls. Similarly, idempotentHint=true conflicts with the described non-idempotent behavior when mark_read is used. This is a serious annotation contradiction.

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

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

The description is packed with essential information but remains well-structured: core action, return fields, filtering/options, behavioral note, and alternative endpoint. Every sentence earns its place without redundancy.

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

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

Without an output schema, the description appropriately explains the return payload and key behaviors (polling, mark_read, feed persistence). It also documents the alternative HTTP GET endpoint. This is complete for a polling tool with five parameters.

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

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

Schema has 100% parameter coverage, so baseline is 3. The description adds value with a concrete type example ('sec_8k'), clarifies 'since' as ISO timestamp, and explains the semantic consequence of mark_read ('next call only shows newer ones'), going beyond the schema's 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 states a specific verb ('Pull') and resource ('fired events from your subscription feed'), and details the return payload (source, citation_uri, raw event payload). This distinguishes it from siblings like 'recent_changes' by focusing on the persisted feed written by the evaluator.

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?

Clear usage context is provided: it supports polling, filtering by type/since, and mark_read to control future calls. It also points to an alternative HTTP endpoint for scripts/dashboards, implying this tool is for in-context polling. Explicit comparisons to sibling tools are absent, but the guidance is 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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description discloses data source fan-out to SEC EDGAR, GDELT/GNews fallback logic, USPTO patent source sunset, and soft-fail behavior. It also explains the return structure (changes[] grouped by source, total_changes, citation URIs), which is essential operational context.

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

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

The description is dense but every sentence earns its place: user-intent examples, mechanism, parameter formats, return structure, and an explicit alternative. It is front-loaded with examples and contains 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?

Given the tool's complexity and lack of output schema, the description fully informs the agent: it explains the multi-source fan-out, fallback behavior, limitation (USPTO soft-fail), the `since` format choices, and the return payload. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds practical guidance for `since` (e.g., "Use '30d' or '1m' for typical monitoring") and ties the parameter to the source windows, exceeding the schema's static definitions.

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

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

The description opens with natural-language examples mapping to user intents, then defines the tool as a 'change feed for a company in the last N days/weeks/months' in one parallel call. It explicitly contrasts with entity_profile, distinguishing it from the most relevant sibling and naming the primary resource (company change feed).

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 concrete query phrasings (e.g., "What's new with X"), specifies the time-window parameter with recommended values ("30d" or "1m"), and explicitly names entity_profile as the alternative when a static profile is wanted. It also describes fallback behavior (GDELT→GNews, USPTO soft-fail), giving clear decision cues.

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 key behavioral traits beyond annotations: scoping by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours) sessions, and the key-value storage model. Annotations already indicate it's not read-only and is idempotent, and the description adds context about memory lifetime and scope without contradiction.

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

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

Four sentences, front-loaded with the primary purpose, then usage context, storage details, and alternatives. No wasted words; every sentence contributes meaningful information.

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

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

The description covers purpose, usage scenarios, persistence behavior, scoping, and related tools. For a simple key-value store with two parameters and no output schema, this is complete and self-contained.

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

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

Input schema provides 100% coverage with detailed descriptions and examples for both key and value. The description reinforces these with use-case examples but does not add new technical details beyond the schema. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'Save' with a clear resource (data needed later) and scope (across conversations or sessions). It distinguishes itself from siblings by naming recall and forget as paired tools. This makes the tool's purpose unambiguous 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?

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and provides concrete examples. It also names alternatives (recall to retrieve, forget to delete), giving the agent clear decision guidance. No explicit 'when not to use' is stated, but the when and alternatives 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?

Discloses several behavioral traits beyond annotations: unresolved identifiers are explicitly listed rather than omitted, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple lookup endpoints. These details significantly enrich the read-only, idempotent profile.

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 front-loaded with example queries and purpose. Every section contributes useful information (types, behavior, degradation), though it could be broken into clearer subsections for easier scanning.

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

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

With no output schema, the description thoroughly explains return values per type, including specific fields, sources, and unresolved handling. It also covers operational context like graceful degradation and cascading lookups, making it complete for effective 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?

Schema already covers both parameters with descriptions; the description adds valuable nuance by showing accepted input formats for each type (ticker, CIK, name for company; brand/generic for drug) and gives examples. This enhances the parameter understanding 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 resolves names to canonical identifiers, with specific verb 'resolve' and resource (entity names). It lists concrete example queries and supported types, and distinguishes itself from sibling tools by positioning as the first step when an ID is needed.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This gives clear context for when to invoke the tool, but lacks explicit when-not conditions or alternative tool references, so it doesn't fully meet the 5-point criterion for exclusions/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 declare read-only, idempotent, open-world, and non-destructive behaviors. The description adds substantial context beyond those flags: it discloses orchestration of ai_visibility_check, describes ranking logic, and specifies the exact output content (score, confidence, signal density). This is genuinely useful behavioral detail.

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

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

Four sentences, each earning its place: purpose, mechanism, use case, and output. The information is front-loaded and free of filler. The example quote is illustrative, not fluff.

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

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

Given the lack of an output schema, the description compensates by explicitly naming return fields (ranked list, score, confidence, signal density). It also covers the tool's internal workflow and the competitive audit context, leaving no critical gap for deciding when and how to invoke it.

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

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

The input schema provides per-parameter descriptions for all four parameters (100% coverage). The description doesn't add syntax, constraints, or parameter-specific meaning beyond what the schema already offers. It reaches the baseline of 3, as the schema carries the semantic burden.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It names the underlying tool (ai_visibility_check), indicates ranking/surfacing behavior, and clearly distinguishes itself from siblings by focusing on multi-entity competitive comparison. The use-case quote reinforces the intended scenario.

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 positions the tool for 'competitive AI-marketing audits' and contrasts 'your brand + N competitors', giving clear contextual when-to-use guidance. However, it does not explicitly name alternative tools or state when not to use it, so a minor deduction for missing 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 read-only/idempotent annotations, the description discloses partial failure behavior, the 5-30s first-measurement latency for bundlephobia, the sources_failed field, and that the rest of results still return. This adds significant behavioral context not available 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 dense but well-structured, leading with the core purpose, then usage, then behavior. The long list of return fields is justified because there is no output schema, but the sentence is somewhat long and could be broken up for easier parsing. Still, every sentence earns its place.

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

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

For a composite tool with no output schema, the description thoroughly covers the returned summary fields, per-advisory details, links, alternative versions, failure semantics, latency, ecosystem scope, and alternative tool usage. No significant gaps remain.

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% (both package and version are described), so baseline is 3. The description adds the constraint 'NPM ecosystem only in v1', clarifying that the package parameter must be an npm package, and provides a concrete example ('lodash') that helps ground the version parameter. But most parameter meaning is already 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 clearly states a specific verb+resource: a composite 'should I add this npm package to my project' check. It distinguishes itself from sibling tools by naming the two data sources (deps.dev and bundlephobia) and the exact question it answers.

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

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

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also clearly states exclusions/alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context about return fields, which is helpful, but it does not disclose pagination limits, result caps, or rate limits. With strong annotations, the additional value is moderate but not exceptional.

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

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

The description is three sentences, with the core function front-loaded. Each sentence adds distinct value: purpose, output, and use case. There is no verbosity, redundancy, or irrelevant detail.

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

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

Given rich input schema (100% coverage) and presence of output schema, the description is largely complete for guiding an agent. It covers what, filters, and result content. Minor gap: no explicit mention of pagination behavior, but the schema's 'page' parameter and examples cover it sufficiently.

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

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

Schema coverage is 100%, providing baseline of 3. The description adds meaning by specifying that 'query' is a name or acronym, which is not explicit in the schema, and it summarizes the type/country filters efficiently. This extra clarity justifies a score 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 uses the specific verb 'Search' with a clear resource 'Research Organization Registry (ROR)' and enumerates the types of institutions targeted. It also states the output fields (ROR id, names, country, types, identifiers) and answers a concrete question ('which ROR id belongs to a named research institution'), differentiating it from sibling tools like 'get' or 'entity_profile'.

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

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

The description provides clear context: use this tool to identify a ROR ID for a named institution, with optional filters. However, it does not explicitly mention when not to use it or compare to alternatives, such as 'search_within' or 'get', leaving some 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 declare readOnly=true and destructive=false, but the description adds substantial behavioral context: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verifiable quotes. These details go well beyond what annotations convey.

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

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

The description is organized into purpose, usage, workflow, and technical details, with each sentence contributing useful information. It is slightly dense but not bloated, earning a 4 rather than a 5.

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

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

Even without an output schema, the description fully explains return values (top-N passages with offsets and similarity scores), input constraints, truncation behavior, and how it complements ask_pipeworx_grounded. This is complete for a tool of this complexity.

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

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

Schema coverage is 100%, and schema descriptions already explain the text, query, and limit. The description reinforces the 'text you already pulled' workflow and gives query examples, but adds little semantic value beyond what the schema already provides, so a baseline 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record', which names a specific verb, resource, and scope. Concrete examples (SEC 10-K, article) and the pairing with ask_pipeworx_grounded clearly distinguish it from the broader sibling `search` and 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?

'Use when the record is too big to cram into the prompt' provides an explicit when-to-use. It also suggests an alternative workflow with ask_pipeworx_grounded ('ground over the relevant passages instead of the whole document'), but does not explicitly describe when not to use this tool beyond that.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses the side effect (creating a persistent subscription), the returned id, account verification requirements, per-channel constraints (SMS 10/day cap, phone verification), webhook signing secret behavior (returned once), and auto-disable after 10 consecutive failing runs. No contradictions with the annotations.

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

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

The description is efficiently organized: purpose first, then requirements, supported types with examples, and delivery channels with caveats. Each sentence adds necessary information, and examples are compact. Though long, the high complexity justifies the length, and there is no fluff.

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

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

Given the tool's complexity (5 subscription types, 3 delivery channels, nested parameters, auth prerequisites), the description covers all essential aspects: what it returns, what auth is needed, how each type's params work, delivery options with verification and limits, webhook security, and failure behavior. No output schema exists, so the description fully compensates.

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

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

Even though schema coverage is 100%, the description massively extends parameter meaning with concrete examples for each type (e.g., sec_8k with items, polymarket_edge with topic, fred_series with series_id), nested object structures for delivery, and critical constraints like 'sponsor or condition required' for clinical_trial. It explains the webhook signing secret and delivery behavior in a way the raw schema does not.

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

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

The description specifies the exact verb ('Create'), the resource ('proactive monitoring subscription to a live-data event stream'), and the return value ('Returns the new subscription id'). It clearly distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation rather than listing, canceling, or consuming alerts.

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

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

The description states a clear prerequisite ('Requires a Pipeworx OAuth account') and explicitly notes when not to use it ('anonymous + BYO cannot persist subscriptions'). It also provides an alternative for consuming alerts without subscribing ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It does not explicitly mention alternatives like list_subscriptions or unsubscribe, 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context: it returns category-bucketed examples with exact tool and argument shape drawn from a live catalog, and mentions it covers thousands of tools. No contradiction with annotations.

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

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

The description is front-loaded with example queries, making it immediately recognizable, then delivers the core purpose. It is a bit long and run-on, but every sentence carries useful information. Slight structural improvement would make it more scannable, so not a 5.

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

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

Given this is a discovery/onboarding tool with no output schema, the description fully covers what it does, when to use it, how to call it, and how it relates to meta-tools. It answers the likely agent questions about purpose and invocation without needing further detail.

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

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

Schema coverage is 100% (the `topic` field description lists all allowed values and the omit behavior). The description adds minor redundancy with 'call with no arguments for the full spread' and a few examples, but does not meaningfully go beyond the schema. Baseline 3 is appropriate.

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

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

The description is specific and actionable: it states the tool 'Returns category-bucketed example questions' and positions itself as the 'onboarding entry point' for an agent. It also explicitly lists meta-tools (ask_pipeworx, entity_profile, compare_entities) to learn from, which distinguishes 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 provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools'. It also details the parameter behavior, saying 'Call with no arguments for the full spread, or pass `topic`'.

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 that the row is deactivated (not deleted) and historical events remain available, which is behavioral context beyond the annotations. It also mentions ownership enforcement. Annotations already indicate idempotent, non-destructive, write operation, and the description adds useful details 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 concise at three sentences, with the primary action front-loaded. Each sentence adds distinct value: the action, the ownership constraint, and the deactivation behavior with a link to recent_alerts.

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, no output schema) and rich annotations, the description is complete. It covers purpose, ownership, side effects, and the relationship to recent_alerts, making it fully adequate for an agent to select and invoke the tool.

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

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

The schema already provides a detailed description for the 'id' parameter ('Subscription id (uuid) returned by subscribe'), covering 100% of the parameter. The description adds no further 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 'Cancel a subscription by id' with a specific verb and resource, and it distinguishes from siblings like subscribe and list_subscriptions by indicating the action of cancellation. The title 'Unsubscribe from Alerts' reinforces the purpose.

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

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

The description provides clear context on when to use the tool (to cancel a subscription) and adds an ownership constraint. It does not explicitly name alternatives, but the reference to recent_alerts for historical events implies an alternative for viewing histories. This is sufficient, though not fully explicit.

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

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

Annotations already signal read-only/open-world/idempotent, and the description adds high-value behavioral detail: the verdict enum, the distinction between 'check didn't happen' and 'no source exists,' the verification_error structure, and routing logic to different data sources. No contradiction.

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

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

Although lengthy, every sentence earns its place: examples, routing, verdict enum, error handling, and the replacement value are all covered. It is densely informative without redundancy.

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

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

Given the absence of an output schema and the tool's complexity, the description is exceptionally complete. It covers routing, return values, edge cases (could_not_verify, unsupported), and the value proposition of consolidating multiple calls.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds extra value by explaining tolerance_pct semantics (default, cap of 5, and use for hallucination detection) and providing natural-language examples for claim.

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

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

The description opens with concrete query paraphrases ('Is it true that…' / 'fact check') and states it performs natural-language claim verification against authoritative sources. It clearly differentiates from sibling research/search tools by specifying a verdict output and noting it replaces 4–6 sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and distinguishes between company-financial claims (SEC EDGAR fast path) and all other claims (grounded pipeline). It also clarifies the meaning of could_not_verify vs unsupported to prevent misuse.

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