Plos

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: the default model (Workers AI Llama-3.3-70b, free), the BYO key for Anthropic with direct payment note, and the per-model return structure. This clarifies cost and execution behavior without contradicting the annotations.

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

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

The description is three tightly written sentences: purpose, key configuration details, and use cases. No redundant words or repetition of schema fields; everything 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?

The tool has 4 parameters, no output schema, and a read-only, non-destructive profile. The description covers the return shape, default model, optional Anthropic probing, cost implications, and typical use cases, making it sufficiently complete for an agent to select and invoke correctly.

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

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

The schema description coverage is 100% for all 4 parameters, so the baseline is 3. The description adds extra value by explaining the default behavior when 'models' is omitted and highlighting the cost implication of passing '_apiKey'. This enriches the param semantics beyond the schema's basic descriptions.

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

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

The description uses a specific verb ('probe') and clearly states the resource (LLMs) and what it produces (a 0-100 visibility score per model). It also names the exact output structure, distinguishing it from similar sibling tools like ask_pipeworx or scan_competitor_ai_presence.

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

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

The description clearly states when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving concrete contexts. It does not explicitly exclude any alternative tools or state when-not-to-use, but the use cases effectively delineate its domain.

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 destructiveHint, covering safety. The description adds value by listing the exact return fields, which helps the agent know what to expect. It doesn't discuss edge cases like invalid DOIs, but given annotations and simplicity, it provides sufficient behavioral context.

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

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

The description is a single, concise sentence that front-loads the main action (fetch by DOI) and lists return fields in a compact list. No wasted words, appropriate length for a simple 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 a single parameter, clear annotations, and an output schema present, the description fully covers the tool's behavior and return values. It is complete for a simple read-only fetch operation.

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

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

Schema coverage is 100% and the schema already describes the 'doi' parameter with an example. The description repeats a similar example in prose, adding no meaning beyond what the schema already provides. This matches 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 states the tool fetches a single PLOS article record by DOI, and lists the returned fields (title, authors, publication date, journal, abstract). This is a specific verb+resource+scope, and it distinguishes from sibling search/recall tools by targeting a single known DOI.

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

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

The description implies the tool should be used when the agent has a specific DOI and needs the article record. However, it does not explicitly state when not to use it or mention alternatives like search tools. The usage context is clear but not explicitly contrasted with siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it routes to the right tool, fills arguments, and returns structured answers with stable pipeworx:// citations. No contradiction. It goes beyond annotations by explaining its routing behavior and output format, which is critical for agent decision-making.

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

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

The description is longer than average but well-structured with clear segments (usage, examples, when to step up). Front-loaded with 'PREFER OVER WEB SEARCH' and benefits from strong organization. Some redundancy (e.g., repeated domain list) but not excessive.

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

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

This is a complex routing tool with no output schema, so the description must convey output behavior. It does so by stating 'returns the structured answer with stable pipeworx:// citations'. It also covers the key scope and alternatives. Adequate but could mention what happens on ambiguity or failure, though not critical for this tool.

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

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

Schema coverage is 100% with all six parameters being aliases for 'question' and a clear description. The tool description doesn't add much beyond the schema—it reiterates natural language acceptance and gives examples, but that serves usage guidance more than parameter semantics. Baseline 3 is appropriate given the schema already handles this.

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

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

The description states a specific verb+resource: 'ask' for real-world factual data via 5,578 tools across 1,463 sources. It clearly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives. The purpose is unambiguous and highly specific.

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

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

The description provides explicit when-to-use triggers ('what is', 'look up', 'find', etc.) and examples. It also gives when-not-to-use with alternatives (ask_pipeworx_grounded for single grounded answers, deep_research for broad multi-part questions). This is textbook usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds important context: the tool is a full working router with no fallback, candidate routing improvements are enabled live when under test, and the last candidate was retired on 2026-07-26. This provides behavioral transparency beyond the annotations, without contradicting them.

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

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

The description is a single dense paragraph that front-loads the beta nature and then covers key behavioral details. It is not overly verbose and each clause adds necessary context (such as 'no candidate active now' and 'falls back to nothing'). Slightly long but efficient for the complexity of the tool.

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

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

For a router tool with no output schema, the description adequately explains the response shape (same as ask_pipeworx) and the experimental nature. It covers the current state, usage, and comparison against stable router. It is complete enough for an agent to invoke correctly, though it could mention any specific routing limitations if any existed (none are present).

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

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

The input schema already describes all parameters with aliases and a clear 'question' description, covering 100% of parameters. The description does not add new parameter details but reinforces that the arguments are identical to ask_pipeworx. Since schema coverage is high, the baseline of 3 is appropriate; the description doesn't add extra semantic value.

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

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

The description clearly states it is a beta version of ask_pipeworx, identical in scope and behavior, and explicitly distinguishes it from the stable router and the grounded variant. It identifies the resource (universal router) and the action (ask), with sufficient specificity to avoid confusion with 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 guidance on when to use this tool: when the newest routing is desired. It also clarifies that it currently matches ask_pipeworx exactly and that results are compared against the stable router for merging decisions. It does not explicitly state when NOT to use it, but the context is clear enough that an agent could infer stable vs. experimental use cases.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, and the description adds substantial behavioral detail beyond those: extraction limited to tool results, explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and return fields including verbatim evidence and confidence. It also discloses the extra LLM call cost, giving the agent practical behavioral 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 but every sentence carries operational value: purpose, routing behavior, extraction constraint, success/refusal return shapes, use-case examples, and cost-based alternative guidance. It is front-loaded with the core purpose and remains appropriately sized for a tool with this much behavioral nuance.

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

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

With no output schema, the description fully compensates by specifying the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the refusal shape with enumerated refusal_reason values. It also covers routing, cost, and use context, making the tool self-sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% with all six parameters being aliases for the same question field, so the schema already fully documents what the caller can pass. The description adds minimal semantic value beyond 'natural language question,' staying at the baseline for well-covered schemas.

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

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

Description clearly states this is a hallucination-resistant answer mode for high-stakes reads, with the specific verb 'extracts the answer using ONLY what the tool result contains.' It distinguishes itself from ask_pipeworx by emphasizing grounded, evidence-backed answers and explicit refusals, making sibling differentiation clear.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples like financial verdicts and legal claims. It also names the alternative (ask_pipeworx) and gives a clear preference rule based on extra cost, providing excellent when/when-not guidance.

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

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

Beyond annotations (readOnlyHint=true, openWorldHint=true), the description discloses numerous behavioral traits: safety short-circuiting for low-confidence matches, closed-market status behavior, wide-spread illiquidity flags, cancellation-rule risk, and news fallback handling (GDELT 429 → GNews). It also explains that resolved markets usually surface via low_confidence_match rather than market_closed_or_inactive, preventing agent misunderstandings.

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 structured into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), front-loading the core action and use cases. Every section provides operational detail an agent needs, and no filler is present. While it's a dense paragraph, the logical structure keeps it navigable.

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

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

There is no output schema, so the description carries the burden of explaining return values. It thoroughly specifies result.market fields, result.analysis fields, evidence structure, resolver contract fields, parent_event extraction, news field fallbacks, and status codes for edge cases. It even quantifies resolution-rule risk with ev_impact, leaving little ambiguity about what the agent will receive.

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 market parameter's description already defines the three accepted formats. The description adds context for how market inputs are resolved (slug/URL/question) and gives examples, but doesn't add new parameter-level semantics beyond the schema. The depth and include_raw parameters have clear schema descriptions and are not elaborated further in the description.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_edges or arbitrage tools by focusing on resolving a specific market and returning evidence. The classifier list and fan-out examples reinforce the focused 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?

Explicit 'Use for' guidance lists question types like 'should I bet on X' and 'what does the data say about Y'. It also describes blocking statuses and when thorough fan-out is triggered, giving the agent clear context. However, it does not explicitly mention when NOT to use this tool or name alternative siblings.

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

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

Despite rich annotations (readOnlyHint, idempotentHint), the description adds substantial behavioral context: it details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics retrieved (revenue, net income, cash, debt; adverse-event counts, approval counts, trial counts), handling of off-calendar fiscal years, and sorting behavior. This goes well beyond the annotations' safety hints.

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

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

The description is longer than average but tightly packed with necessary information: trigger phrases, tool behavior, type-specific details, and output format. It is front-loaded with the most important usage cues and avoids fluff. Minor redundancy exists (e.g., "2–5" appears in both description and schema), but overall every sentence earns its place.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It explains what data is returned for each entity type, how results are ordered, and that citation URIs are included. Combined with annotations for safety (read-only, idempotent), an agent has all necessary context to invoke this tool correctly without guessing.

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

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

Schema coverage is 100% for both parameters, but the description adds meaning by explaining what each type enum values do (type='company' pulls 10-K data; type='drug' pulls FAERS/FDA/trial data) and reiterating values as tickers/CIKs or drug names. It also clarifies that results are sorted by primary metric, which relates to how the parameters shape output. Slightly less exhaustive than describing each parameter individually, but adds clear value.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, using specific trigger phrases like "Compare X and Y" and "head to head." It explicitly distinguishes itself from sibling tools by noting it replaces 8–15 sequential lookups, making its purpose and scope unambiguous.

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

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

The description provides explicit when-to-use guidance: trigger phrases like "X vs Y" and "which is bigger" indicate when this tool should be invoked. It also instructs to "ALWAYS PREFER over sequential single-pack lookups when comparing entities," directly naming the alternative (sequential lookups, likely via sibling tools like entity_profile) and when not to use it.

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

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

Extremely transparent about behavior: describes parallel decomposition, hop mechanics (gap recovery), contradictions[] scanning, citation_uri resolvability, semantic excerpting of large records, latency expectations (15-90s), and the honest gaps[]/never-invented policy. This massively exceeds the annotations (readOnly, openWorld, idempotent, non-destructive), which only cover half the picture. It adds critical context about latency, authentication, paid tiers, and the structured-data limitation.

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

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

The description is long but dense with value. Every clause earns its place: auth, alternatives, behavior, depth semantics, citations, latency. It could be tightened slightly (the last sentence about semantic excerpting could be folded), but it is front-loaded with the most critical info (account required, alternative tool) and organizes details logically. Slight over-length for the 10% criterion, hence 4.

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 2 parameters, 100% schema coverage, and no output schema, the description is exceptionally complete. It explains the response format (findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), which is critical since there is no output schema. It also covers the tool's fit among 30+ siblings, auth, pricing, latency, and limitations. This is a model of completeness.

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

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

Schema coverage is 100%, but the description significantly enhances meaning of the 'depth' parameter by explaining what each level does (quick=3 facets single hop, standard=3 with gap recovery + contradictions, thorough=6 with iterative hopping + contradictions) and adds the paid-tier restriction for thorough. It also builds on the natural-language question parameter by explaining decomposition behavior. This is additive, not redundant.

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

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

The description states precisely what the tool does: it conducts grounded multi-source research across Pipeworx's 1,463 structured data sources in one call, decomposing the question into facets and routing to 5,578 tools in parallel. It clearly distinguishes from sibling tools like ask_pipeworx, search, and compare_entities, explaining its unique value proposition (broad/multi-part structured-data research vs single lookups).

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

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

Explicitly states when to use this tool vs alternatives: use for broad/multi-part questions over structured data, use ask_pipeworx for single lookups and breaking/current news topics. Also provides clear account requirements (free sign-in, paid for thorough depth) and directs unauthenticated users to ask_pipeworx. The 'not open-web search' warning and structured-data framing are strong usage guidance.

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

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

Beyond the annotations (read-only, idempotent), the description discloses return behavior: returns top-N most relevant tools with names, descriptions, and full input schemas, ready to call directly without a second lookup. This adds useful context about output format and reusability, though it could mention pagination limits explicitly.

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, efficiently structured: purpose, use-case, and return behavior. No fluff, front-loaded with the primary action, and every sentence earns its place.

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

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

For a discovery tool with no output schema, the description is complete: it explains what it returns, how results are structured, and when to invoke it. It also covers domain areas and the 'Call this FIRST' guidance, making it self-sufficient for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it mentions 'describing the data or task' which maps to 'query', and 'top-N' hints at 'limit', but these are already fully documented in the input schema. No additional value.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It uses a specific verb ('Find') and resource ('tools'), and explicitly lists the domains it covers, distinguishing it from sibling tools like search 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?

Provides explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives a clear condition and a prioritization heuristic, effectively differentiating from direct-answer 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the multi-source fan-out (SEC, XBRL, USPTO, news, GLEIF), the soft-fail behavior for patents due to API sunset, the GDELT→GNews fallback, and the parallel execution model. These are valuable behavioral details not captured 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 front-loaded with user-intent examples and a clear summary statement. It packs many needed details (outputs, fallbacks, input rules) into one paragraph, but it is a long wall of text that could be slightly better organized with separators.

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

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

For a complex multi-source tool with no output schema, the description covers input constraints, output fields, source caveats, and fallback behavior thoroughly. The only minor ambiguity is the exact meaning of 'soft-fails', but overall it is remarkably complete.

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

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

Schema coverage is 100% with both parameters fully described (type enum and value with ticker/CIK examples). The description's parameter guidance mostly repeats the schema content (zero-padded CIK, resolve_entity fallback), adding little new semantics beyond the structured documentation.

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

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

The description clearly states it produces a 'full cross-source profile of a US public company in ONE parallel call' and lists specific outputs (CIK, filings, fundamentals, patents, news, LEI). It also includes concrete user-intent examples like 'Tell me about X' and 'research Acme', and distinguishes itself from single-pack SEC/XBRL/news lookups.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which tells when to use it. It also provides an explicit exclusion: 'names not supported (use resolve_entity first if you only have a name)', directing to a sibling tool for the alternative case.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds context about clearing sensitive data and previously saved memories, but it doesn't disclose additional behavioral traits beyond what annotations convey, such as what happens if the key doesn't exist. It meets the baseline but doesn't exceed it.

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 short sentences, each serving a distinct purpose: stating the action, specifying usage scenarios, and naming related tools. There is no redundant information, and it is front-loaded with the core function.

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 destructive and idempotent annotations, the description provides clear purpose, usage context, and related tools. It is fully sufficient for an agent to select and invoke the tool correctly, and no return-value details are necessary without an output schema.

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

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

The input schema provides 100% coverage with the key parameter described as 'Memory key to delete'. The description adds no additional meaning about the parameter beyond the schema, so it aligns with 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 states 'Delete a previously stored memory by key', which specifies both the action (delete) and the resource (memory by key). This distinguishes it from sibling tools like remember and recall, which are for storing and retrieving memories respectively.

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

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

The description explicitly lists when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, but doesn't explicitly state when not to use it or contrast with alternatives, so it falls just short of a 5.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context by disclosing that it fetches the page, extracts title/description/key links, and emits standard markdown. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loads the primary action, and each sentence serves a distinct purpose: what it does, how it works, and when to use it. There is no redundancy or filler.

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

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

For a tool with only two parameters and a single text output, the description covers the main behavior, the output format, and practical use cases. The existing annotations and complete schema reduce the burden, making this description complete enough for an agent to invoke it correctly.

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

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

The input schema provides 100% coverage for both parameters ('url' and 'max_links') with clear descriptions. The tool description adds no additional parameter-specific guidance beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description opens with 'Generate a production-ready llms.txt file for any URL' which is a specific verb+resource statement. It further explains the process (fetches, extracts, emits) and clearly differentiates the tool from siblings by focusing on the llms.txt output format.

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

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

The description provides concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly name alternative tools or exclusion criteria, but the use cases are specific enough to guide when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds value by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that it returns the caller's own subscriptions, which is additional context not present in annotations.

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

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

The description is two sentences, front-loaded with the primary action, and includes usage guidance without unnecessary detail. 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?

Given the simple parameter set, rich annotations, and the absence of an output schema, the description provides sufficient context by listing the return fields and usage scenario. It fully enables an agent to understand what the tool does and when 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 has 100% description coverage, with the include_inactive parameter fully documented in the schema. The description does not mention this parameter, so it adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the action: 'List the caller's active subscriptions.' It identifies the specific resource (subscriptions) and scope (caller's). It also distinguishes itself from sibling tools like subscribe and unsubscribe by mentioning review and cancel purposes.

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 sentence 'Use this to review what you're monitoring before adding more or to find an id to cancel' provides explicit usage context, implying when this tool is appropriate relative to subscribe/unsubscribe. However, it does not explicitly name alternatives or state when not to use it.

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

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

Annotations provide no hints (all false), so the description carries the full burden. It discloses the claim_token return/read flow, rate limiting (5 per identifier per day), free status (no quota deduction), and that the team reads digests daily. These details go well beyond the schema and annotations, offering rich behavioral context.

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

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

The description is long but every sentence contributes value: purpose, use cases, exclusion, token flow, rate limit, and free status. It is front-loaded with the core action and well-structured, though slightly lengthy. It earns its place but could be trimmed marginally for perfect conciseness.

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

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

For a feedback tool with no output schema, the description explains the full workflow: when to use it, what happens (returns claim_token), how to follow up, and limitations. Combined with high schema coverage, the description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptive parameter docs, so the baseline is 3. The description adds meaningful cross-parameter guidance, especially for claim_token (how to pass it back later) and message content (don't paste user prompts, be specific). This enriches parameter semantics beyond what the schema alone 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the action (send feedback), the resource (Pipeworx team), and the scope (improvements). It distinguishes the tool from siblings by focusing on feedback submission rather than research, search, or recall functions.

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

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

The description explicitly lists when to use the tool: for bugs, feature/data gaps, and praise. It also states a clear exclusion: if the tool came from a different MCP server, file it with that server instead. This provides strong guidance on when to use 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, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it explains the data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and aggregate nature. This enriches behavioral understanding.

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

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

The description is well-structured and front-loaded with the core statement, then bulletized use cases. It is somewhat long but every sentence adds value—privacy, caching, and selection guidance. No wasted words.

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

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

The tool is simple (one optional param) and the description covers its purpose, return content, use cases, caching behavior, and data source. No output schema exists, but the description sufficiently explains what the agent can expect from the response.

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

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

The schema already describes the 'window' parameter with enum values and a description. The description adds interpretive meaning about shorter vs longer windows ('hot right now' vs 'steady-state demand'), which goes 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: it returns top tools, top packs, and total call volume over a window, aggregating what other AI agents are using. It distinguishes itself from siblings like discover_tools by focusing on current usage trends, not discovery.

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 use cases are provided, giving clear context for when to use the tool. However, it doesn't explicitly name alternative tools or state when not to use it, 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, non-destructive). It discloses detailed internal behaviors: how event mode walks child markets and checks date/threshold ordering, how topic mode performs cross-event flattening, the ≥0.30 Jaccard similarity anchor, placeholder filtering, and the fill check with realizable vs theoretical edge. This level of detail ensures the agent understands what happens under the hood and what results to trust.

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 packs critical information with clear structural labels (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK). Every sentence serves a purpose: mode selection, examples, thresholds, response format, and usage caveats. There is no fluff or repetition, making it appropriately sized for the tool's complexity.

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

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

Without an output schema, the description compensates by outlining the response structure (opportunities[], partition_check, suggested_trade, etc.) and covering key edge cases: fill-check conditions, similarity threshold, placeholder handling, and the 'do not trade if realizable_edge_pp ≤ 0' rule. This is complete enough for an agent to invoke the tool correctly and interpret results.

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

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

Although the schema already provides 100% coverage of the two parameters, the description adds substantial meaning beyond the schema. It explains that 'event' switches to single-event mode with a slug or URL, gives concrete examples, and contrasts it with 'topic' mode. It also clarifies optional behavior when no args are provided (trending_scan), which the schema omits. This enriches parameter understanding significantly.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges (edge detection) and polymarket_fill_risk (fill risk) by naming the unique arbitrage-detection approach and multiple scan modes.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also provides recommendations ('event (recommended for a specific market)') and points to an alternative tool for sizing ('For custom sizing use polymarket_fill_risk'). This gives clear context for choosing this tool over others.

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 is exceptionally transparent about internal behavior: it explains how edges are computed (net of slippage), the Kelly caps, the 24h-move warning, the tradeable-edge knobs, the diagnostic funnel, and the 1h KV caching. This goes far beyond the simple readOnlyHint=true annotation, adding valuable context about response structure, filtering logic, and potential edge cases (e.g., 'your edge may already be in the price').

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 and dense, but the main purpose is front-loaded, and the content is organized into clear sections (model families, response segments, tradeable-edge knobs, response top-level) using capitalization and parentheses. Every sentence carries substantive information, so it is not wasteful, though it could be seen as overly verbose. A 4 balances its thoroughness against its lack of brevity.

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

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

Despite having no output schema, the description fully specifies the response structure (by_segment, fed_candidates/fed_note, _diagnostics) and covers all important aspects: model families, filters, knobs, caching, and diagnostics. It is complete enough for an agent to understand exactly what will be returned and why a segment might be empty, making it very well-suited for autonomous 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 description coverage is 100%, and each parameter is already well-explained in the input schema (e.g., min_liquidity, slippage_pp have detailed descriptions). The tool description reinforces these knobs in prose ('TRADEABLE-EDGE KNOBS') but does not add significant new meaning beyond what the schema already provides. It earns the baseline 3 but no higher.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames the use case ('what should I bet on today'), which gives strong clarity. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it stops short of a 5.

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

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

The description provides clear context for when to use the tool: 'agents discover opportunities without paging hundreds of markets' and 'Built for "what should I bet on today"'. It also mentions exclusions (Fed bets excluded from ranking). However, it does not explicitly name alternatives or state when not to use it, so it lacks the explicit when/when-not contrast needed for a 5.

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

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

The description goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by explaining data availability (cache-miss snapshots, 60-day TTL), the computation basis (daily closes, not intraday), and the meaning of gaps in snapshot_dates. This is rich behavioral context that helps the agent understand limitations and interpret results.

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

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

The description is long but well-structured with clear sections (intro, args, response, limits). It is front-loaded with the core purpose. Each sentence adds useful information, though some phrasing like 'the latter is wide for a reason nobody is willing to take' is slightly editorial. Overall, it earns its place with minimal waste.

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 the response structure (tracked[], expired[], snapshot_dates[]) and their semantics. It also covers edge cases like missing snapshot gaps, TTL limits, and computation details. This is a complete picture for a moderately complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the parameter defaults ('days (lookback, default 14, max 30)', 'window ... default 1wk') which are already in the schema, and does not add additional semantic meaning beyond what the schema descriptions provide. Thus it meets but does not exceed the baseline.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge age and decay. This distinguishes it from siblings like polymarket_edges (which likely lists current edges) and polymarket_arbitrage (which likely detects arbitrage opportunities).

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

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

The description explains when this tool is valuable: 'a fresh wide edge and a 3-week-old wide edge are different trades' and mentions the median lifespan as a 'competition clock'. It does not explicitly name alternative tools, but the context and sibling list make the differentiation clear. It lacks explicit exclusions but provides strong 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 readOnly/idempotent annotations, the description reveals substantial behavioral details: it walks the ladder, varies behavior by mode, reinterprets size_usd for basket mode, and returns a verdict plus forced_directional_risk. It also warns about the dominant loss mode in arb-bot P&L, which is well beyond 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 highly structured: a one-sentence purpose, REQUIRES directive, two clearly-labeled mode blocks, and a practical 'USE THIS' paragraph. Every sentence is information-dense and earns its place; 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 must convey return values, and it does: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, per-leg fills, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers modes, defaults, constraints, and risk implications, making the tool fully 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?

Although schema coverage is 100%, the description adds critical semantics: it explains that market and event are mutually exclusive modes, defines side choices per mode, gives defaults, and clarifies that size_usd means spend/proceeds in single-market mode but settlement notional in basket mode. This transforms bare parameter names into full operational understanding.

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

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

The description opens with a specific verb phrase ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and then details two distinct modes with exact outputs. It clearly distinguishes itself from sibling tools by explicitly referencing polymarket_arbitrage and polymarket_edges signals.

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 an explicit trigger: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable; partial fills create directional risk), making the usage context unmistakable.

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 read-only, open-world, idempotent, and non-destructive, and the description adds substantial behavioral detail: response includes leg-by-leg prices, compatibility_warning conditions for non-equivalent bet shapes, temporal_alignment flags, and skip counters. It also explicitly states that pre-mapped ≠ tradeable, which is a critical behavioral caveat.

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 unique information, with clear structural markers (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. The prose is dense but organized, making the length 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?

Since there is no output schema, the description fully specifies the response structure: leg-by-leg prices, matched spread[], top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers edge cases and limitations, making it a self-contained guide for the tool's usage.

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

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

The schema provides descriptions for all three parameters (100% coverage), and the description enriches them by explaining the two-mode semantics: the topic param auto-fetches matching events via shortcuts, while the explicit params override the mapped side. This clarifies how the parameters interplay beyond their individual schema descriptions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which precisely states the tool's function and differentiates it from same-venue arbitrage tools like polymarket_arbitrage. It further details two operational modes (topic shortcuts vs explicit identifiers), making the purpose unmistakable.

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

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

The description explains when the spread is a 'real signal' (equivalent bet shapes) and when it isn't, and warns that most pre-mapped topics return compatibility_warning today. This provides clear guidance on when to use the tool, though it does not explicitly name alternative tools for same-venue queries.

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, destructiveHint=false, which cover the safety profile. The description adds valuable behavioral context beyond those annotations: the subtlety of omitting the key to list all saved keys, and scoping to the user's identifier. It does not contradict annotations, and adds enough extra nuance to merit a 4.

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

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

The description is two sentences, front-loaded with the core action. It avoids repetition, each clause adds meaningful information (pairing with remember/forget, scoping), and no word is wasted. This is a model of concise, structured writing.

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

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

For a low-complexity tool with one optional parameter and no output schema, the description is fully sufficient. It covers purpose, usage, paired tools, scoping, and listing behavior. The annotations already provide read-only and idempotency context, 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?

Schema coverage is 100%, so baseline is 3. The description reinforces the parameter behavior ('omit the key argument' to list) and enriches semantics by providing concrete examples of key values (user's target ticker, an address, prior research notes). This goes slightly beyond the schema, which only says 'Memory key to retrieve (omit to list all keys)'.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes the tool from siblings by mentioning remember and forget as paired operations and providing concrete use cases (ticker, address, research notes). This is a precise, unambiguous statement of 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 states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the companion tools 'remember' and 'forget' for save and delete operations, and explains scoping (anonymous IP, BYO key hash, account ID). This gives explicit context and alternatives, though it does not explicitly say when NOT to use it, the context is strong enough.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description only needs to add behavioral context. It adds the 'across PLOS' scope and recency ordering, but does not explain default result limits, pagination, or how 'recent' is defined. This modest addition merits a midpoint score.

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

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

The description is one short, front-loaded sentence with no filler. It is appropriately concise for a simple list tool, and every word carries meaning.

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

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

With an output schema present and strong annotations, the description does not need to explain return format, but it still omits key invocation details such as the purpose of the 'rows' parameter and the definition of 'recent.' For a simple tool this is adequate but leaves gaps.

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

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

The schema has one optional parameter 'rows' with 0% description coverage, and the description does not mention or explain this parameter. The property name and example (25) provide minimal inferable meaning, but the description fails to compensate for the missing schema documentation.

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

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

The description identifies the resource as PLOS publications and clearly implies a retrieval action ('Most recent publications'), distinguishing it from sibling tools like recent_alerts or recent_changes. However, it lacks an explicit verb such as 'lists' or 'returns,' which slightly weakens the purpose clarity.

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

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

No guidance is given on when to use this tool versus alternatives like search, search_authored_by, or recent_alerts. The phrase 'Most recent publications across PLOS' implies a use case but does not state exclusions, prerequisites, or alternative conditions.

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

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

Beyond the readOnlyHint annotation, the description discloses a meaningful side effect: setting mark_read:true flags events so later calls only show newer ones. It also reveals the alternative direct URL and describes the return payload structure, adding substantial context beyond what annotations and schema provide.

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

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

Three sentences, each earning its place: first states the action, second describes the payload and filtering, third explains mark_read and the alternative endpoint. Front-loaded with the core purpose, 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?

With no output schema, the description compensates by specifying that each alert carries source, citation_uri, and the raw payload. It covers filtering, mark_read semantics, and provides an alternative access method, making the tool fully usable from the description alone.

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

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

Schema coverage is 100%, but the description enriches parameter meanings—e.g., giving an example value for type ('sec_8k') and clarifying the effect of mark_read beyond the schema's basic description. This adds value above the baseline for fully-documented schemas.

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: 'Pull fired events from your subscription feed.' It clearly distinguishes this from siblings by detailing the feed source, return fields, and filtering capabilities. The purpose is unambiguous and not a tautology.

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 context for usage: 'Polls work fine' and offers an alternative HTTP endpoint for scripts and dashboards, which implies when not to use the tool. It also explains mark_read behavior for subsequent polling. However, it doesn't compare against sibling tools explicitly, but the guidance is clear.

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

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

Beyond annotations, the description discloses multi-source fan-out, fallback sequencing, the USPTO PatentsView API sunset causing soft-fail, and the exact return structure (changes[] by source, total_changes, pipeworx citation URIs). No contradictions 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 dense but every sentence adds value—example queries, source details, fallback logic, parameter syntax, return shape. It is front-loaded with user-phrase examples, though it remains a single lengthy paragraph that could benefit from bullet points for scannability.

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

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

Given the tool's complexity (multi-source, fallbacks, soft-fails), the description covers all critical aspects: when to use, parameter formats, source behavior, failure modes, output structure, and a pointer to the sibling tool. No output schema exists, so the description's return-value explanation is essential and provided.

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

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

Schema already covers all three parameters (100% coverage). The description adds practical guidance: 'since' accepts ISO date or relative shorthand, typical monitoring values ('30d' or '1m'), and 'value' can be ticker or zero-padded CIK. This augments the schema with use context.

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: a change feed for a company across SEC EDGAR, GDELT/GNews, and USPTO. It uses a specific verb phrase ('change feed') and resource scope, and explicitly contrasts with sibling entity_profile ('static profile') to eliminate ambiguity.

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

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

The description opens with natural-language query examples ('What's new with X') and includes explicit alternative guidance: 'Use entity_profile instead when you want the static profile...' It also provides operational context on fallback behavior (GDELT preferred, GNews on rate-limit) and notes when the tool is appropriate for monitoring windows.

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 idempotent=true and readOnly=false. The description adds valuable context beyond annotations: scope by identifier, session-vs-persistent retention, and that it stores key-value pairs. It does not state overwrite behavior, but the idempotent hint partially covers that. No contradiction found.

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 five short sentences, each earning its place: purpose, usage example, storage details, persistence, and relationships to siblings. It is front-loaded with the primary action and avoids redundancy.

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

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

For a simple two-parameter tool with no output schema, the description is complete: it explains what, when, how, persistence, and related tools. No return format is needed, and the annotations cover safety profile. There are no gaps.

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

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

Schema description coverage is 100% for both key and value, so the baseline is 3. The description adds semantic examples (ticker, address, preference, subject) that clarify what keys/values should represent, slightly elevating value beyond the schema.

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

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

The description clearly states the tool saves data for later reuse, using the specific verb 'Save data' and the resource 'key-value pair.' It distinguishes itself from the sibling tools recall and forget by explicitly mentioning pairing with them, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives/companions: 'Pair with recall to retrieve later, forget to delete,' and clarifies persistence behavior for authenticated vs. anonymous sessions, giving clear context for choosing this tool.

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

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

The description adds substantial behavioral context beyond the annotations: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit reporting of unresolved identifiers under `unresolved`, and source labelling for every identifier. This is exactly the kind of non-obvious behavior an agent needs to know.

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-organized with examples and a clear SUPPORTED TYPES section. Every sentence carries functional value, though the density of parenthetical details makes it somewhat less scannable than it could be. It is not bloated, but it is borderline verbose.

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

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

Despite having no output schema, the description thoroughly covers what the agent will receive: labelled identifiers, unresolved items, fallback behavior, and ownership data. It also addresses both entity types and internal cascade behavior, making it complete for this tool's complexity.

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

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

Although the schema already covers parameters 100%, the description greatly enriches them: it specifies accepted input formats (ticker, CIK, ISIN, or company name; brand or generic name), gives examples, and explains the ISIN-to-LEI mapping nuance. This adds meaningful guidance beyond the bare schema 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 clearly states the tool's purpose with specific verbs and resources: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from siblings by focusing on identifier resolution and even says 'Use FIRST whenever you have a name but need an ID.' Supported types and concrete examples reinforce a well-defined purpose.

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

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

It provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and notes that it replaces 2-3 manual lookups. However, it does not explicitly name alternative tools such as entity_profile or compare_entities or state when not to use this tool, leaving the boundaries somewhat implicit.

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

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

The description adds meaningful behavioral details beyond the annotations, such as 'Probes each entity ... with ai_visibility_check, ranks by score' and describes the return format ('score, confidence, signal density per entity'). Annotations already cover read-only and idempotent behavior, so the description's additional workflow information earns a solid score. 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 two dense sentences, front-loaded with the primary action, then internal mechanics, use case, and output summary. Every sentence adds value with no wasteful repetition 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 has no output schema, the description compensates by stating the return type ('ranked list with score, confidence, signal density per entity'). It also explains the workflow and use case. Minor gaps such as not detailing how the models parameter affects probes are covered by the schema, so overall completeness is strong.

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 already descriptive parameter definitions (e.g., entities, models, _apiKey, context). The description reinforces the entities parameter ('your brand + N competitors') but does not add syntax or format details beyond the schema. Per calibration, a baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's function with specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It also distinguishes itself from sibling tools like ai_visibility_check by detailing that it probes entities with that tool, ranks by score, and surfaces most/least recognized, making its unique value explicit.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with an example query. It implicitly differentiates from single-entity tools by naming ai_visibility_check as the underlying probe, but it does not explicitly state when not to use this tool or name alternatives like compare_entities, so it lacks explicit exclusion guidance.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral detail: multi-source fan-out, graceful degradation, 5-30s first-measurement delay, and the sources_failed mechanism. It goes far beyond annotations.

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

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

The description is dense but well-structured, opening with the core purpose, then a bullet-like enumeration of return fields, and finally failure-mode caveats. Every sentence provides unique value and unnecessary words are absent.

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 (multiple sources, no output schema, potential timeouts), the description covers the full set of returned fields, source behaviors, failure handling, and ecosystem boundaries. It leaves the agent with a complete mental model.

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

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

The input schema has 100% description coverage for both parameters, so the baseline is 3. The description doesn't add new parameter-level semantics, but it reinforces version usage context ('specific version to check' and default behavior) in a way that aligns with 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 explicitly states the tool performs a composite 'should I add this npm package to my project' check, naming the exact data sources (deps.dev, bundlephobia) and key output fields. This clearly distinguishes it from sibling tools like scan_competitor_ai_presence.

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

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

It gives explicit usage triggers ('whenever an agent asks "is X safe / popular / small"'), specifies NPM-only scope, and directs users of other ecosystems to deps.dev:version directly. This is model behavior for when-to-use and exclusion guidance.

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

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

Annotations already cover read-only, idempotent, and non-destructive hints. The description adds meaningful behavioral context: the Solr engine, field-qualified query syntax, default return fields, and support for pagination/sorting/custom fields. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core purpose and followed by capabilities and defaults. Every sentence adds value, 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?

Given the presence of an output schema and comprehensive annotations, the description covers the essential behaviors: scope, query syntax, available operations, and default fields. It could delve into edge cases like result limits or error handling, but it is largely sufficient for a search tool.

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

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

Schema descriptions cover 4 of 5 parameters (80%). The description reinforces parameter usage by giving a concrete example of a field-qualified query and mentioning pagination, sorting, and custom field selection, which map to start/rows, sort, and fl. It also notes the default return fields, helping clarify fl values. However, the 'start' parameter is not explicitly explained beyond 'pagination.'

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 'Solr-powered full-text search across all PLOS open-access journals,' which clearly specifies the action (search), the resource (PLOS journals), and the scope (all open-access). It also lists distinct capabilities (field-qualified queries, pagination, sorting, custom field selection), setting it apart from sibling tools like search_authored_by or search_within.

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

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

The phrase 'across all PLOS open-access journals' provides clear context for when to use this tool. However, it does not explicitly mention when not to use it or name alternatives such as search_within or search_authored_by, so it lacks explicit exclusionary guidance.

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

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

The description adds no behavioral detail beyond the annotations; annotations already declare read-only, idempotent, and non-destructive. There is no mention of pagination, matching behavior, or limitations, so the description adds minimal value.

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

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

At six words, the description is undeniably short, but the brevity results in a fragment that omits key information; it is not well-structured for an AI agent.

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

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

Given the tool has an output schema and rich annotations, the description could suffice if it explained the parameters and usage, but it does not. The lack of explanation for 'rows' and any context about result limits makes it incomplete.

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 0%, and the description only hints at the 'name' parameter via 'by author name.' The 'rows' parameter is entirely unexplained, and no format or syntax guidance is provided.

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 phrase 'Articles by author name' clearly identifies the resource (articles) and the filter (author name), though it lacks a verb and does not explicitly differentiate from the broader 'search' siblings. It conveys the core function effectively.

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 no information about when to use this tool instead of siblings like 'search' or 'search_within', and no preconditions or exclusions are mentioned.

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 reveals behavioral details beyond annotations: the embedding model (BGE-base-en), cosine similarity over 500-char windows, and the 200K character cap with truncation flagging. These are not in the annotations and give the agent crucial expectations about performance and limitations.

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 yet information-dense, with each sentence serving a purpose: stating the core function, explaining the use case, and detailing technical behavior. No filler or repetition; it front-loads the primary action.

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

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

Given the absence of an output schema, the description adequately explains what is returned (top-N passages with offsets and similarity scores). It covers the input requirements, limits, and how it integrates with related tools, making it self-sufficient for an agent to use 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 already describes each parameter thoroughly, including examples for the query. The description adds context about the text being 'already pulled' and the query being natural language, but this does not materially enhance understanding beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside an already-fetched record, distinguishing it from siblings by emphasizing it operates on text the user provides rather than a global search. It gives concrete examples (SEC 10-K, article) and mentions the specific output (passages with offsets and similarity scores), making its purpose unmistakable.

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

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

Explicitly states when to use this tool: when the record is too big to fit in the prompt. It also pairs with ask_pipeworx_grounded, providing a clear alternative for grounding over relevant passages. This gives the agent actionable guidance on tool selection.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds valuable behavioral context: OAuth requirement, return of subscription id, always-on feed, phone verification for SMS, and a 10/day cap. 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 a single paragraph, front-loaded with the primary purpose, and every sentence provides actionable information. It is somewhat long but appropriately so given the number of supported types and delivery options.

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

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

For a complex tool with three nested parameters and no output schema, the description is remarkably complete. It covers return value, authentication prerequisites, all supported types with examples, delivery channels, and constraints. The absence of an output schema is mitigated by explicitly stating the returned subscription id.

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

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

Schema coverage is 100%, but the description adds semantic examples (e.g., items:[5.02] = officer change) and clarifies delivery requirements (verified phone). This enriches the parameter understanding beyond the schema's structured 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 clearly states the tool's purpose with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation.

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 create a persistent subscription for live data monitoring) and states an explicit exclusion: anonymous and BYO accounts cannot persist subscriptions. It does not explicitly name alternative tools, but the guidance is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context about the return format (category-bucketed example questions with tool + argument shapes) and the optional topic parameter. It also clarifies that the data comes from a live catalog, which is beyond the annotations.

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

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

The description is well-structured: it starts with user-intent phrasings, defines the tool's role, explains the return value, gives call instructions, and ends with usage priority. Each sentence contributes new information, with 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?

Despite lacking an output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool and argument shape). It covers the single optional parameter, the no-argument default, and the intended use case. The description is sufficient for an agent to decide when and how to invoke it.

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

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

The input schema covers the single `topic` parameter with a full description and enum-like list. The description adds a few examples ("finance", "pharma", "betting") and the concept of "full spread" vs. "focus", but this is largely redundant with the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly identifies the tool as the onboarding entry point for Pipeworx, using specific verbs like "suggests" and "returns" example questions. It distinguishes itself from siblings by focusing on the use case of discovering what to ask and how to call meta-tools, unlike ask_pipeworx or search.

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

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

The description provides explicit guidance: "Use this FIRST when you do not yet know what Pipeworx can do for you" and explains when to pass a `topic` vs. no arguments. It does not explicitly name alternatives, but the context of "onboarding" and "not yet know" makes the 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 goes beyond annotations by explaining ownership enforcement and that the row is deactivated rather than deleted, preserving historical events via recent_alerts. This adds meaningful context about side effects and data retention, consistent 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?

Three sentences, front-loaded with the primary action, then two concise clarifications about ownership and soft-deletion. No wasted words or redundancy.

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

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

For a single-parameter tool with no output schema, the description fully covers purpose, usage constraints, and post-action behavior. It references recent_alerts appropriately, making the context complete.

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

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

The schema has 100% coverage for the single parameter, describing it as a subscription ID returned by subscribe. The description adds no new parameter details but is consistent with the schema, so the baseline 3 applies.

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

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

The description clearly states the tool cancels a subscription by ID, with a specific verb+resource pairing. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation and soft-deactivation behavior.

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 context clearly implies when to use (when canceling a subscription) and mentions ownership enforcement. While it doesn't explicitly list alternative tools or exclusions, the guidance is adequate for a simple tool and is reinforced by the contrast with subscribe and list_subscriptions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description explains the critical distinction between 'could_not_verify' and 'unsupported', warns callers not to treat 'could_not_verify' as evidence, and discloses the structured vs grounded routing and citation behavior. No contradiction with annotations.

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

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

The description is long but well-structured, front-loaded with trigger phrases, and each paragraph adds value—especially the caller warning about 'could_not_verify.' It is slightly verbose but justified for a tool with complex output semantics.

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

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

With no output schema, the description fully documents the return verdicts, the actual value plus citation, reasoning, and the important failure-mode semantics. It also explains the internal routing and why this tool replaces multiple calls, making it complete for agent invocation.

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

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

Schema coverage is 100%; both 'claim' and 'tolerance_pct' already have detailed schema descriptions. The tool description adds context about exact percent-delta math and tolerance implied by wording, but it does not add significant new parameter semantics beyond what the schema already provides, warranting the baseline 3.

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

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

The description opens with natural-language triggers and explicitly defines the tool as 'natural-language claim verification against authoritative sources.' It distinguishes itself from sibling research/search tools by naming the two distinct verification paths and by stating 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 gives an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the routing for company-financial claims vs other factual claims, but does not name specific sibling alternatives or exclusions, so it stops short of 5.

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