uluesky

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context: the default model is free, passing `_apiKey` incurs direct Anthropic charges, and returns a per-model structure with score/confidence/signals/raw_response. This discloses cost implications and behavioral details beyond the annotations, though it does not cover potential rate limits or failure modes.

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

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

The description is two sentences long, front-loaded with the core function, and contains no redundant phrases. It efficiently packs the model options, cost note, return format, and use cases without fluff.

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

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

The tool has no output schema, but the description compensates by listing return fields ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers default behavior and optional API key usage. However, it does not explain what 'signals' contain or how the visibility score is computed, which could be important for an agent to trust the output. Overall, it is well-rounded for a read-only probing tool.

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

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

The input schema already has 100% parameter coverage with detailed descriptions for each field. The description reinforces but adds little new meaning (e.g., names the exact default model 'Llama-3.3-70b' and repeats the BYO key cost note). Since schema coverage is high, a baseline of 3 is appropriate; the description contributes minimal additional semantics.

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

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

The description clearly states a specific action ('Probe one or more LLMs') and target ('business / brand / product / topic') with an output ('score visibility 0-100 per model'). It is specific and unambiguous, but it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', which may have overlapping functionality.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default and optional configurations, giving clear context for when to use the tool. However, it does not mention when NOT to use it or compare it to alternatives like 'ask_pipeworx' or 'deep_research'.

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 open-world hints. The description adds valuable behavioral context: automatic routing to thousands of tools, stable citation URIs, works on every tier, and one fast call. It does not contradict annotations, though it could mention potential failure modes (e.g., no source found) or rate limits. Overall, it enriches the safety profile with operational details.

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

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

The description is long but densely packed with essential information: purpose, domain list, examples, comparisons to alternatives, and tier compatibility. Every sentence earns its place, but the length could be slightly trimmed for faster scanning. Still, it is well-structured with a clear directive opening.

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 meta-tool with no output schema, the description fully covers what the agent needs: it explains what the tool does, what it returns (structured answer with citations), when to use it, when to use alternatives, and provides concrete examples. The breadth of the tool is handled well, making it complete for selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already documents the 'question' parameter and its aliases clearly. The description adds illustrative examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K') but no additional syntax or format details, so it 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 explicitly identifies what the tool does: routes questions to one of 5,564 tools across 1,462 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

Provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when-not-to-use alternatives ('Step up only when needed: ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions'). Lists concrete trigger phrases and examples, giving agents clear decision rules.

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, it discloses live candidate routing improvements, the current no-candidate state, and that it 'Falls back to nothing' — making clear this is a full working router, not an incomplete wrapper. No contradiction exists with the readOnly, idempotent, or non-destructive 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, with the key fact front-loaded and useful details such as the candidate retirement date and the 'falls back to nothing' clarification. There is slight redundancy between 'identical... same... same...' and 'matches ask_pipeworx exactly,' but no filler.

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

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

For a simple one-required-param tool, it fully covers current behavior, change rationale, and relationship to the stable router. The lack of an output schema is partly mitigated by 'same response shape,' though the actual shape is not described, so the agent must already know ask_pipeworx's response format.

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 100% of parameters and documents all aliases for question, so the description does not need to add parameter-level detail. It only references 'same arguments' as ask_pipeworx, which is a pointer rather than additional semantic content. Baseline 3 is appropriate.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router' and explicitly scopes it to the same 5,564 tools, same arguments, and same response shape. This clearly distinguishes it from the stable ask_pipeworx sibling while naming the experimental difference.

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 states 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This gives a clear selection criterion and names the alternative stable router. It also clarifies that no candidate is currently active, so behavior matches the stable version exactly.

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 indicate a safe read-only, idempotent operation, and the description adds substantial behavioral detail: it only answers from data contained in the tool result, returns explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and includes evidence as a verbatim quote. This goes far beyond what annotations alone provide.

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

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

Every sentence earns its place: the purpose, mechanism, return shape, refusal behavior, usage context, and cost trade-off are all covered in a dense but well-structured paragraph. It is front-loaded with the core value proposition and remains readable despite its length.

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 no output schema, the description fully compensates by specifying the exact success and refusal response shapes, listing all refusal reasons, and clarifying behavioral boundaries like refusing when data doesn't directly answer. Combined with strong annotations and a simple single-question input, this is complete.

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

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

Schema description coverage is 100%, with all six parameters being aliases for a single natural-language question. The description does not add parameter-level meaning beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description clearly defines a distinct tool: a hallucination-resistant, grounded answer mode that routes through the same underlying machinery as ask_pipeworx but extracts answers only from tool results. It explicitly contrasts with the sibling ask_pipeworx, making its unique value 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?

Provides explicit when-to-use guidance: high-stakes reads where answers will be quoted, cited, or acted on, such as financial verdicts, legal claims, medical lookups, and public statements. It also names ask_pipeworx as the preferred alternative for casual lookups and discloses the extra LLM call cost, giving clear trade-off guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It discloses the resolver contract (market_match_confidence, market_match_score, alternatives, suggestions), the blocking low_confidence_match and market_closed_or_inactive paths, the parent_event extractor, the news fallback fields, wide-spread tradeability warnings, and resolution-rule risk (e.g., refund_50_50 void settlements). This is exceptionally transparent about edge cases and failure modes.

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

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

The description is front-loaded with a clear purpose sentence, and section labels (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) improve scannability. However, it is extremely long and includes overlapping safety explanations (low_confidence_match, closed markets, wide-spread) that could be consolidated. While most sentences carry useful detail, the sheer volume crosses from thorough to verbose, making it less concise than ideal.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It details response shapes, resolver alternatives, parent-event partition aggregation, news fallback behaviors, safety short-circuits, illiquidity warnings, and cancellation-rule parsing. An agent has enough context to know what to expect and how to handle ambiguous or low-confidence results without needing 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning to the 'market' parameter by explaining the three accepted formats (slug, URL, question text) and how the tool resolves and classifies them. It also clarifies fan-out behaviors per category, enriching the parameter's role. The 'depth' and 'include_raw' parameters are already well-described in the schema and the description adds no extra semantics there, keeping this at a 4 rather than 5.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines the input (slug, URL, question text) and output (evidence packet + market-vs-model comparison). This distinguishes it from siblings like validate_claim or polymarket_edges by emphasizing the one-call research fan-out for any Polymarket bet.

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

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

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides classifier examples that hint when category-specific data packs apply. However, it does not explicitly name alternative tools to prefer in other scenarios (e.g., for pure market data or arbitrage), so it stops short of full when-not-to-use guidance.

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

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

The description goes well beyond the annotations by disclosing specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and output containing paired data with citation URIs. This adds substantial context without contradicting the read-only/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 carries actionable information. It front-loads the core purpose and usage triggers, then efficiently covers data sources, parameter semantics, and output characteristics without redundancy. The structure helps an agent quickly grasp when and how to invoke 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 tool with no output schema, the description explains what the user gets back (paired data + citation URIs), how results are ordered, and the distinction between company and drug data. It even notes that it replaces 8–15 sequential lookups, giving the agent a full picture of the tool's value and behavior.

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

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

Although the schema provides descriptions for both parameters, the tool description enriches them significantly—it explains what data each 'type' pulls (e.g., latest 10-K revenue, net income, cash, long-term debt for companies; FAERS counts and trial counts for drugs) and gives concrete examples for the 'values' array. This goes beyond the schema's 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 identifies the tool as a side-by-side comparison of 2–5 companies or drugs in a single call, with specific verbs like 'compare', 'rank', and 'head to head'. It also distinguishes itself from sequential single-entity lookups, setting it apart from sibling tools like entity_profile and resolve_entity.

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

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

The description explicitly states when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and provides example user phrasings that trigger comparison intent. It also gives context for the 'type' parameter (company vs drug) and clarifies that results are sorted for easy interpretation.

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 richly discloses behavior beyond the readOnly/openWorld/idempotent annotations: account and paid-plan requirements, latency (15-60s, up to ~90s for thorough), gap[] handling (never invented), contradictions[] scan, semantic excerpting, and the conditionality of citation_uri. This is substantial added context that helps an agent set expectations and handle outcomes.

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 high-value information: auth, alternatives, output packet details, limitations, depth semantics, and timing. It is front-loaded with the critical account requirement. Some example phrases and exact tool counts could be trimmed, but the length is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return structure (findings packet, gaps[], contradictions[], hop field, citation_uri) and process behavior. It also covers auth prerequisites, alternatives, latency, and edge cases (unsupported topics). For a complex tool, this is exceptionally complete.

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

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

The schema already describes both parameters fully (100% coverage). The description adds extra context by explaining depth-specific behaviors (e.g., standard's gap-recovery hop, thorough's lead-chasing), the paid requirement for thorough, and the expected latency per depth. This meaningfully complements the schema, though much is already embedded in the 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 clearly states the tool performs grounded multi-source research across 1462 structured data sources, decomposing questions into facets and routing them to thousands of tools in parallel. It uses a specific verb ('research') and resource, and distinguishes itself from open-web search and ask_pipeworx. The scope and one-call nature are 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 extensive when-to-use guidance: it is best for broad/multi-part questions over structured data, while single lookups and breaking news should use ask_pipeworx. It also details the alternative tool for unsigned-in users and explains the depth tiers with their recovery/contradiction behavior. This explicit exclusion and alternative naming goes beyond basic context.

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

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

Annotations already provide read-only/idempotent safety, but the description adds valuable behavioral details: returns top-N tools with names, descriptions, and full input schemas, results are 'ready to call directly' with no second lookup, and it positions itself as a first-call discovery tool. No contradictions with annotations.

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

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

The description is well-structured and front-loaded: first sentence gives the core purpose, then use cases, return format, and strategic guidance. The domain list is long but informative, and every sentence earns its place without redundancy.

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

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

Without an output schema, the description compensates by explaining what is returned (tool names, descriptions, full input schemas, curated examples) and the tool's role as a discovery aid. It covers usage context and result behavior; only minor details like ranking order are omitted, but overall it is sufficient for a search/discovery 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 description coverage is 100%, and the schema already explains the query parameter and aliases. The description reinforces the query concept ('describing the data or task') but adds no extra meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific action ('Find tools by describing the data or task') with a clear resource (the tool ecosystem). It covers the tool's scope (SEC filings, financials, FDA drugs, etc.) and explicitly frames it as a discovery/browse option, distinguishing it from sibling tools like search_posts 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?

'Use when you need to browse, search, look up, or discover what tools exist' gives explicit contexts, and 'Call this FIRST when you have many tools available' provides strong when-to-use guidance. However, it does not name specific alternative tools for cases where you already know the target tool, though 'not just one answer' implies this.

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, it discloses the exact return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and notes the USPTO PatentsView API sunset with soft-fail behavior, plus GDELT→GNews fallback. This adds rich behavioral context not available in annotations.

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

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

The description is dense and well-structured with examples and a clear list of outputs. It is slightly longer than ideal, but every section serves a purpose, making it appropriately concise for the complexity.

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

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

With no output schema, the description enumerates the return structure, input constraints, and failure modes (patents sunset, news fallback), making it fully sufficient for correct invocation. It leaves no critical gaps.

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

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

Schema coverage is 100%, so the schema already fully documents the 'type' and 'value' parameters, including the ticker/CIK format and the resolve_entity note. The description merely repeats this information without adding new parameter semantics.

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

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

The description opens with concrete user queries and states 'full cross-source profile of a US public company in ONE parallel call', clearly distinguishing it from sibling tools like deep_research or single-pack lookups. The verb 'profile' and resource 'US public company' are specific and 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?

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and warns that names are not supported, directing to resolve_entity. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark the tool as destructive and idempotent; the description adds that it clears sensitive data saved earlier and that deletion is by key. This gives useful context about the intent and scope 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?

Three short sentences lead with the core action, then provide usage guidance and sibling context. No redundant text or filler.

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

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

For a simple one-parameter delete operation with destructive/idempotent annotations, the description covers purpose, usage, and context sufficiently. No output schema is expected for such an operation, so the absence of return-value details is not a gap.

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

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

The input schema fully describes the only parameter ('Memory key to delete'), and the description reinforces the need for a key. Since schema coverage is 100%, the description doesn't need to add further parameter semantics, meeting the baseline.

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

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

The description uses the specific verb 'Delete' and identifies the resource as 'a previously stored memory by key', making the tool's function immediately clear. It also distinguishes itself from sibling memory tools by instructing to pair with 'remember and recall'.

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

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

It provides explicit usage conditions ('when context is stale, the task is done, or you want to clear sensitive data'), which tells an agent when to invoke it. It does not formally state when not to use it or name an alternative for retrieval, but pairing with remember/recall offers some directional guidance.

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

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

The description goes beyond the annotations by explaining the internal behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also discloses the output form ('single text blob ready to drop at site-root/llms.txt'). This adds practical behavioral context that aligns with the readOnlyHint and openWorldHint annotations, without contradiction.

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

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

The description is three sentences of appropriate length. The first sentence states the core action, the second explains the process, and the third lists use cases. Every sentence earns its place, with no redundant content or filler.

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

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

Despite having no output schema, the description adequately explains what the tool does, how it works, what the output looks like, and when to use it. Given the tool's relative simplicity (2 parameters, one required), the description is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' already described in the schema. The description adds minimal extra parameter context; it implies the URL is fetched and that the output is a standard format, but these are already inferable from the schema. As per the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It specifies the verb (generate), the resource (llms.txt file), and the scope (any URL). The process is outlined ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'), which distinguishes it from any sibling tools that only check AI visibility or scan presence. The description is specific and unambiguous.

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

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

The description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives strong contextual guidance on when to use the tool. However, it does not explicitly mention when not to use it or compare it to alternative tools, so it falls short of a top score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds return content details (authors, timestamps, engagement counts) and feed examples, but does not disclose other behavioral aspects like pagination or error handling. This adds moderate value 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 two concise sentences, front-loaded with the main purpose and followed by return content. No unnecessary words 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 simple tool semantics, complete annotations, and an output schema, the description is mostly complete. It covers purpose, return content, and feed examples, though it lacks explicit error cases or behavior for invalid feeds. The minor inconsistency in the example feed_uri is a small gap.

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

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

Schema covers both parameters (limit, feed_uri) with descriptions, so baseline is 3. The description adds example feed_uri values, though with slight inconsistency (e.g., 'whatshot' vs 'whats-hot'). It does not significantly clarify parameter semantics 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 gets posts from a Bluesky feed, with specific examples like 'discover' and 'what's-hot'. It distinguishes from sibling tools like get_posts by specifying the feed context.

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

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

The description implies usage for retrieving feed content but does not explicitly mention alternatives or when not to use it. It lacks comparison with similar tools like get_posts or search_posts, leaving the agent to infer the appropriate context.

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

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

Annotations already convey read-only, open-world, idempotent, and non-destructive behavior. The description adds that follower profiles are returned, but does not mention pagination, rate limits, or other nuances. It does not contradict annotations.

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

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

The description is two short sentences: the first states the core action, the second summarizes the return value. No unnecessary 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 simple 2-param tool with strong annotations and an output schema, the description is sufficient. It could mention pagination or ordering, but those are not critical for basic use and the schema/annotations already cover safety and parameters.

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

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

Schema coverage is 100%: both handle and limit have clear descriptions. The description simply notes 'by handle,' which aligns with the schema but adds no new semantic detail beyond the structured parameter 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 uses a specific verb and resource: 'Get a user's followers on Bluesky by handle.' It also enumerates the returned fields (handles, display names, bios, follower counts), making the tool's purpose clear and distinguishing it from siblings like get_follows.

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 does not explicitly state when to use this tool versus alternatives such as get_follows. Usage is implied by the name and phrasing, but no when-not or alternative guidance is provided.

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=false, covering safety. The description adds that it returns profiles with certain fields, but this is likely redundant with the output schema. No additional behavioral traits (e.g., pagination, rate limits) are disclosed.

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

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

The description is a single, front-loaded sentence with no filler. It conveys the essence efficiently.

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

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

For a simple read-only getter with comprehensive schema annotations and an output schema, the description is sufficiently complete. It covers the core function without needing to detail return values or edge cases.

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

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

Both parameters have full descriptions in the schema (100% coverage), so the baseline is 3. The description doesn't add meaningful parameter-level semantics beyond restating the handle use case.

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

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

The description clearly states the tool's action ('Get accounts a Bluesky user follows by handle') with a specific verb and resource, effectively distinguishing it from sibling tools like get_followers and get_profile. The scope is unambiguous.

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

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

The description clearly indicates the use case for retrieving a user's follow list, but it doesn't explicitly mention alternatives or when not to use it. Context is clear, though exclusionary guidance is absent.

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. The description adds return field details but does not disclose operational behavior like pagination, ordering, time windows, or rate limits. With annotations covering the safety profile, this modest addition earns a 3.

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 concise sentences, front-loaded with the primary action and followed by return details. Every word earns its place, with no redundancy or fluff.

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

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

For a simple read-only tool with an output schema and good annotations, the description covers the core purpose and return contents. Missing usage guidance and operational details are minor gaps given the tool's simplicity, but overall it is sufficiently complete.

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

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

Schema description coverage is 100% for both parameters (handle and limit), including the limit's range and default. The description adds no additional parameter meaning 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 clearly states the verb 'fetch' and the resource 'recent posts from a Bluesky user's timeline', and lists return fields. It is specific but does not explicitly differentiate from sibling tools like get_feed or get_thread, 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 gives no guidance on when to use this tool versus alternatives such as search_posts or get_thread. There is no mention of prerequisites, exclusions, or preferred contexts, so the agent must infer usage from the tool name alone.

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 this as read-only, idempotent, and non-destructive, providing the safety profile. The description adds that it returns display name, bio, counts, avatar, and verification status, but since an output schema exists, this is somewhat redundant. It does not disclose error behavior or rate limits, but for a simple read-only lookup with strong annotations, a 3 is appropriate.

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

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

The description is two sentences, front-loaded with the action and resource, includes an example handle, and summarizes return fields. Every sentence adds value, with no filler or repetition of annotation data.

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 one-parameter read-only tool with rich annotations and an output schema, the description is fully adequate. It covers what the tool does, how to invoke it (by handle), and what to expect in the response. No additional context is necessary for correct selection and invocation.

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

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

Schema description coverage is 100%, and the description does not add meaning beyond what the schema already provides. The handle format and example are present both in the schema description and the schema examples. The description reinforces the example but introduces no new semantic detail, matching the baseline for well-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 clearly states the tool's function: 'Look up a Bluesky user's profile by handle' with a specific resource (profile) and scope (by handle). It distinguishes from siblings like get_followers/get_follows by listing return fields (display name, bio, counts, avatar, verification status), which is unique to profile lookup.

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

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

The description provides clear context: use this tool to look up a profile by handle. It implies the appropriate use case for retrieving profile details, though it does not explicitly mention alternatives or exclusions. Given the sibling list, a direct comparison would have earned a 5, but the absence of explicit 'when not to use' guidance keeps it at 4.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by disclosing the return structure: parent post + replies in conversation order with timestamps, authors, and engagement data. This goes beyond the annotations, providing useful 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 well-structured sentence that front-loads the action and resource, then lists the return contents. Every word earns its place with no redundancy or filler.

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

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

With only one parameter, an output schema, and annotations covering safety, the description is fully complete. It even goes beyond requirements by explaining the return payload (timestamps, authors, engagement data), making the tool's behavior clear.

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% (post_uri is fully described with example and format). The description does not add any additional parameter information beyond the schema, so the baseline score of 3 is appropriate. No gap to compensate.

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 'Fetch a post thread by URI' with a specific verb and resource, and distinguishes itself from sibling tools like get_posts by focusing on thread structure (parent + replies). The return content is explicitly listed.

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

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

The description implies usage context (fetching a thread by URI) but does not explicitly state when to use this tool over alternatives like get_posts or search_posts. No exclusions or alternative references are provided, so the guidance is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds value by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and scoping to the caller's subscriptions. This is useful context beyond the annotations, though it does not elaborate on rate limits or pagination.

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: the first states the core purpose and return fields, the second provides usage guidance. Every word earns its place, and the information is front-loaded for quick comprehension.

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 comprehensive annotations, the description is complete. It covers the purpose, return shape, and appropriate usage scenarios, leaving no significant gaps for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with the include_inactive parameter already described as 'Include cancelled subscriptions in the response (default false).' The description's mention of 'active subscriptions' aligns with the parameter semantics but does not add additional meaning. Thus, the baseline of 3 applies.

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

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

The description clearly states the tool's function: listing the caller's active subscriptions. It specifies the resource (subscriptions) and the verb (list), and the inclusion of 'caller's' and 'active' distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states when to use the tool: to review current monitoring before adding more (i.e., before subscribe) or to find an id to cancel (i.e., before unsubscribe). This provides clear context and implies the alternatives, making the usage guidance actionable.

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

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

Beyond the annotations (all false), the description discloses key behaviors: the claim_token flow for checking resolution, daily digest reading, rate limiting to 5 per identifier per day, and that it is free and doesn't count against quota. This adds significant behavioral context not present in structured fields.

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

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

The description is dense and front-loaded: the first sentence states the purpose, followed by usage conditions, exclusions, the claim_token mechanism, and rate limits. Every sentence carries actionable information with no filler or repetition.

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

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

Despite having no output schema and four parameters (one nested), the description covers expected return behavior (claim_token), the rate limit, and the exact scenarios for use. It includes enough detail for an agent to decide when to call, what arguments to provide, and what to expect back. The sibling list confirms no overlapping feedback tool.

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

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

The input schema already documents all four parameters with detailed descriptions (100% coverage). The description adds semantic guidance beyond the schema, particularly for claim_token (how to pass it back to read the reply) and message (don't paste the end-user's prompt, describe in terms of Pipeworx tools). Slight deduction because context subfields aren't elaborated further, but the schema covers them.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly scopes the tool to feedback about Pipeworx tools and distinguishes it from all sibling tools, none of which are feedback-related.

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

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

The description explicitly states when to use the tool: for bugs (wrong/stale data), feature requests, data gaps, and praise. It also provides a clear when-not: if the tool came from a different MCP server, file it there instead. This is exemplary guidance with an alternative named.

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 annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds valuable context: it is self-aggregating, derived from CF analytics-engine, contains no PII, and has a caching policy (5min-1h depending on window). This goes beyond annotations and helps the agent understand the data source and freshness.

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 purpose. It uses a numbered list for use cases and compact clauses for extra details (data source, PII absence, caching). Every sentence adds value without redundancy, making it efficient despite its length.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all relevant aspects: what it returns, available time windows, when to use it, data provenance, and caching behavior. There are no significant gaps given the tool's complexity.

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

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

The input schema already provides 100% coverage for the single 'window' parameter, including enum values and a description explaining the trade-offs between shorter and longer windows. The main description mentions the window option but does not add new semantic detail beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description opens with a clear, specific purpose ('What other AI agents are calling on Pipeworx right now') and lists exact return values (top tools, top packs, total call volume). This distinguishes it from siblings like discover_tools or ask_pipeworx by focusing on aggregate trending data rather than discovery or Q&A.

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 an explicit 'Useful for' list with three concrete use cases (discovering hot data sources, confirming canonical tool choice, aligning with agent needs). This gives clear context for when to use the tool, though it does not explicitly state when not to use it or name alternative tools.

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

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

Adds substantial behavior beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains side effects/limitations: 'PARTITION FILTER: drops placeholder slugs... return null arb signal,' 'FILL CHECK: ... realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it,' and 'skipped_low_similarity surfaces the rejected pair count.' These are critical behavioral details not derivable from annotations.

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

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

The description is long but exceptionally well-structured with embedded section labels (SEMANTIC ANCHOR, PARTITION FILTER, Response, FILL CHECK). The first sentence states the core purpose, and every subsequent sentence adds necessary operational detail for the tool's complexity. No filler or redundant repetition.

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

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

For a complex tool with no output schema, the description compensates by outlining response fields: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade},' and the fill-check fields. It also covers edge cases (low similarity, placeholder fraction), making it fully self-contained for an agent to decide invocation 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?

Despite full schema coverage, the description enriches both parameters: explains event slug format and that full URLs are accepted, defines topic as a seed question, and details how each parameter changes execution (walks child markets, checks ordering, runs comparator on flattened union). It also provides concrete examples for both, exceeding 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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' which immediately states the verb (Find), resource (Polymarket), and specific mechanisms. It clearly distinguishes from siblings by naming alternate modes (event vs topic vs no-args trending_scan) and even references polymarket_fill_risk for sizing, making the tool's unique role obvious.

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 each input mode: 'Call with NO args for a trending_scan,' 'pass event for the strongest per-event partition_check,' 'topic for a themed cross-event scan.' It also gives concrete examples (fed-decision-may-2026) and recommends event for specific markets, plus points to an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: caching (1h KV), diagnostics for empty segments, model assumptions (lognormal barrier, GDELT ratio), the 24h-move warning, Fed signal unreliability, and per-leg Kelly design for partitions. It also clarifies edge_pp_net is after slippage and includes 'rare-by-design' gate notes.

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

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

The description is long but front-loaded with purpose, then structured from model families → knobs → response structure. While dense and including specific alpha values, each clause contributes necessary information for invoking correctly. The logical organization compensates for length.

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

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

Despite no output schema, the description enumerates top-level response fields (by_segment, fed_candidates, _diagnostics), lists what every opportunity carries (edge_pp_net, kelly_fraction, market.liquidity, market.spread_pp, etc.), and explains why segments may be empty via funnel counters. It also covers caching and filter knobs, making it highly complete for a complex 9-param 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 100% of the 9 parameters, so the baseline is 3. The description adds value by explaining parameter interplay: min_kelly does not apply to partition_overround because parent Kelly is zero by design, while min_partition_leg_kelly applies per-leg; it also clarifies that slippage is subtracted net before ranking and Kelly sizing.

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

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

The description states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from siblings by focusing on Pipeworx model disagreement and explicitly names the use case ('what should I bet on today').

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 explains tradeable-edge filters, but it does not explicitly name alternative tools or state when not to use it. The implied usage is clear, though explicit exclusions are absent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds substantial behavioral context: response structure, snapshot TTL limits, cache-miss data gaps, decay computation on daily closes (not intraday), and the meaning of expiry. This goes well beyond the annotations and richly discloses edge cases.

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

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

The description is long but efficiently structured with ARGS, RESPONSE, and LIMITS sections. Every clause provides operational value (e.g., 'snapshots are written when polymarket_edges runs on a cache-miss'), with no filler or repetition. It front-loads the core question and provides structured detail.

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

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

With no output schema, the description carries full burden for return values, and it delivers: it details the tracked[], expired[], and snapshot_dates[] arrays, field semantics, and even explains the 'median lifespan' as a competition clock. Combined with limits on history depth and gap behavior, it is complete for a telemetry tool of this complexity.

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

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

Schema coverage is 100% for both parameters, including defaults and allowed values. The description restates 'days (lookback, default 14, max 30)' and 'window (snapshot family, default 1wk)', but adds little beyond the schema. It does clarify that window refers to snapshot family, a minor addition. Per the rubric, baseline 3 is appropriate when 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 purpose: it provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. This is a specific verb+resource combination that distinguishes it from sibling tools like polymarket_edges (which likely lists current edges) by focusing on historical persistence.

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

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

The description implies when to use the tool vs alternatives by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It references 'built from daily polymarket_edges snapshots' to position it relative to the base tool. However, it does not explicitly name alternatives or state when not to use it, leaving contextual inference to the agent.

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

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

Annotations already declare readOnly/idempotent, but the description adds rich behavioral context: it 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and for basket mode returns per-leg details, thin_legs[], and forced_directional_risk. It also explains how size_usd is interpreted differently across modes.

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 each sentence earns its place: it packs purpose, modes, parameter semantics, return fields, risk warnings, and usage guidance into a dense but well-structured paragraph. The use of ALL-CAPS for mode names and key constraints improves 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?

For a complex two-mode tool with no output schema, the description is remarkably complete. It covers all return fields, parameter interpretation, risk caveats, and when to use the tool. No critical usage detail 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?

Even though the schema already covers all parameters at 100%, the description adds meaning beyond field names: it explains the market vs event modes, size_usd as 'max spend on buys, target proceeds on sells' or 'settlement notional S', and the auto default for basket side based on partition sum.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by positioning it as the pre-trade fill-risk check for those strategies.

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 instructs when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why partial fills convert arb into unhedged directional risk, and distinguishes single-market vs basket modes.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing behavior like compatibility_warning firing conditions, temporal alignment constraints, skipped_cross_type/subtype counters, and that spreads are only meaningful when bet shapes match. It also explicitly states when no arb exists, providing deep insight into internal logic.

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 (modes, response, safety fields). Every sentence adds relevant detail about behavior, safety, or usage. It could be slightly tightened, but given the tool's complexity, the length is justified and front-loaded with the core purpose.

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

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

With no output schema, the description thoroughly explains the response structure: per-venue leg prices, matched_spread with top_spreads_pp, and safety fields. It covers all major aspects of input, output, and edge cases, making the tool's behavior fully understandable without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable semantics by explaining how topic mode auto-fetches matching events and how explicit parameters override the topic-mapped side, enriching the schema's bare descriptions with mode interaction logic.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with explicit mention of 'spread' and 'same resolving question'. It distinguishes itself from siblings like polymarket_arbitrage by emphasizing cross-venue comparison and safety checks on bet-shape equivalence, making the purpose unique and 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 clearly explains two modes of use (topic shortcuts vs explicit ticker/slug) and warns that most pre-mapped topics currently return compatibility_warning, guiding agents to not assume tradeability. It lacks explicit mention of alternative tools but provides strong contextual guidance on when the tool is appropriate and what to expect.

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

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

Given that annotations already declare readOnly, idempotent, and non-destructive behavior, the description adds valuable context: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID), and it can operate in two distinct modes (retrieve by key or list all keys). No contradiction with annotations.

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

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

The description is concise and front-loaded: the first sentence gives the core action and the mode-switch behavior. The second and third sentences add use cases, scoping, and sibling relationships without any redundant filler.

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

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

For a simple one-parameter memory-retrieval tool with no output schema, the description covers the main behavior, the listing variant, the storage context, and privacy scoping. It provides enough for an agent to select and invoke the tool correctly without needing further information.

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

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

The input schema already describes the single 'key' parameter with 100% coverage, including the omit-to-list behavior. The description reinforces this but does not add significant new parameter-level meaning beyond what the schema provides.

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

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

The description clearly states the verb ('Retrieve') and resource ('a value previously saved via remember'), and immediately contrasts this with the list-all-keys mode. It also distinguishes itself from sibling tools by naming remember and forget as the complementary save/delete counterparts.

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 when to use the tool: 'look up context the agent stored earlier' and 'without re-deriving it from scratch.' It also provides alternative tools ('Pair with remember to save, forget to delete') and clarifies the trigger for list mode ('omit the key argument').

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 annotations indicating readOnly and idempotent hints, the description discloses an important side effect: setting mark_read:true flags events as read, altering future calls. It also details the payload structure and notes that polling is safe. This adds value beyond the annotations, though it stops short of discussing rate limits or auth.

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 tersely written, with each sentence contributing new information. It opens with the core action, then layers in return details, filtering, mark_read semantics, and a polling note, all without redundancy.

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

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

Since there is no output schema, the description compensates by outlining the returned fields (source, citation_uri, raw payload). It covers filtering, mark_read side effects, polling suitability, and even provides an external endpoint. This is fully complete given the 5-parameter, no-output-schema context.

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

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

With 100% schema description coverage, the schema already documents parameters. The description adds value by providing concrete examples (e.g., type 'sec_8k') and explaining the behavioral effect of mark_read and since filters, which enriches the parameter semantics 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 'Pull fired events from your subscription feed' with a specific verb and resource, and further clarifies it returns the most recent alerts with fields like source and citation_uri. This distinguishes it from sibling tools like get_feed or subscribe, which serve different 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 description explains filtering options and the mark_read behavior, which is a clear usage context. It also provides an alternative for scripts/dashboards via a URL, implying the tool is for interactive use. However, it does not explicitly contrast with sibling tools like get_feed, so it lacks explicit exclusions.

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

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

Annotations state readOnly/openWorld/idempotent. The description adds significant behavioral context: fans out across multiple sources, GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fails due to PatentsView sunset, and returns changes[] grouped by source. This is exactly the kind of extra transparency that helps agents anticipate side effects and failure modes.

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

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

The description is dense but well-structured: front-loaded with intent-revealing examples, then a clear summary, followed by source details, parameter guidance, output shape, and an alternative. Every sentence adds value; no filler or redundancy.

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

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

For a multi-source aggregation tool with no output schema, the description covers all necessary context: sources, fallback logic, API sun-setting caveat, date formats, output structure (changes[], total_changes, citation URIs), and alternative tool usage. This is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description goes further: it explains `since` accepts ISO or relative shorthand with examples and recommends '30d' or '1m' for typical monitoring, and clarifies `value` can be a ticker or zero-padded CIK. This enriches parameter understanding beyond the schema.

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

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

The description provides specific verbs and resources: 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists fan-out sources (SEC EDGAR, GDELT/GNews, USPTO). It clearly distinguishes from sibling entity_profile by stating when to use that instead.

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?

Includes realistic example natural-language queries ('What's new with X'), gives parameter usage guidance ('Use "30d" or "1m" for typical monitoring'), and explicitly names an alternative tool: 'Use entity_profile instead when you want the static profile.' This is strong 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?

The description adds valuable behavioral context beyond annotations: memory is key-value scoped by identifier, persistent for authenticated users, and retained for 24 hours for anonymous sessions. No contradiction with provided 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 tightly-worded sentences, each earning its place: main purpose, usage trigger with examples, and persistence details. 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?

For a simple key-value store with two parameters and no output schema, the description provides complete guidance on purpose, usage, persistence, and companion tools. It covers all essential aspects without needing 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?

Schema already fully documents both parameters with examples, so baseline is 3. The description adds the key-value pairing concept and scoping by identifier, slightly enhancing understanding of how parameters relate.

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 across conversations or sessions, using the specific verb 'save' and resource 'data'. It distinguishes itself from sibling tools recall and forget by explicitly pairing with them.

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

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

It provides explicit when-to-use guidance with concrete examples (resolved ticker, target address, user preference) and tells the agent to pair with recall and forget for retrieval and deletion. This clearly contrasts with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (all benign). The description adds rich behavioral context: it cascades through GLEIF, OpenFIGI, and SEC EDGAR; degrades gracefully if services are unavailable; returns unresolved identifiers explicitly; and explains ISIN-to-LEI mapping. This goes far beyond what annotations provide, fully informing the agent of the tool's internal behavior and edge cases.

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

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

The description is relatively long (10+ sentences) but well-structured and front-loaded with example queries and a usage directive ('Use FIRST'). Every sentence provides distinct value, covering input types, output details, and fallback behavior. Some redundancy exists (e.g., the ISIN explanation could be shorter), but overall it balances comprehensiveness with readability.

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

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

There is no output schema, so the description must fully explain the return value. It does: identifiers are labelled with source, unresolved identifiers are explicit, RxCUI includes a citation, and LEI/FIGI enrichment is conditional. This is complete for a tool that performs entity resolution across multiple sources. Given the complexity (multiple lookup cascades), the description leaves minimal ambiguity.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by clarifying input formats (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company; 'brand or generic name' for drug). It also explains special behavior for ISIN input (resolves to legal entity via GLEIF). This enhances the schema's static enum/string descriptions.

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

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

The description uses specific verbs ('resolve...name to canonical/official identifiers') and provides concrete example queries. It clearly differentiates from siblings like 'entity_profile' (which likely provides more detail after resolution) and 'resolve_handle' (which resolves user handles). The supported entity types ('company', 'drug') and identifier outputs (CIK, LEI, FIGI, RxCUI) are explicitly stated, making purpose unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' This is strong guidance. It also explains that the tool replaces 2-3 manual lookups, justifying its use. However, it does not explicitly mention when NOT to use it or what sibling tools to use instead when you already have an ID (e.g., entity_profile for details). Nonetheless, the provided guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds that it returns a DID but doesn't disclose additional behavioral traits like error handling or edge cases. This is acceptable given the annotations but not rich.

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

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

Two concise sentences, no wasted words, front-loaded with the core purpose. Efficient and clear.

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 an output schema, the description is adequate. It explains the transformation and the intended use. It doesn't cover edge cases, but none are essential given the simplicity.

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 the parameter 'handle' described as 'Bluesky handle to resolve'. The description doesn't add extra meaning beyond that, so the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Convert' and clearly identifies the resource (Bluesky handle) and the output (DID). It distinguishes from sibling tools like resolve_entity by limiting scope to Bluesky handles and explicitly mentioning programmatic account lookups.

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

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

The description implies when to use the tool: 'for programmatic account lookups' provides clear context. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusions.

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

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

The description adds useful behavioral context beyond the annotations: it probes each entity, ranks by score, surfaces most/least recognized, and returns score/confidence/signal density. It does not contradict the readOnly/idempotent hints, and while it doesn't detail error handling or rate limits, the annotations already cover safety.

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 with a clear front-loaded purpose, a concrete use case, and a return-type summary. Every sentence earns its place—no fluff or repetition of schema details.

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

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

Despite no output schema, the description outlines the return shape (ranked list with score, confidence, signal density). It also explains the internal mechanics (probes each entity) and the multi-entity scope. Missing minor details like error behavior or rate limits, but sufficient for selection and basic invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the first-entity-as-subject concept and highlights ranking, but it does not add new parameter-level details beyond what the schema already provides for models, _apiKey, and 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 states a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), and clearly differentiates from siblings by mentioning it probes each entity with ai_visibility_check and ranks them. It also gives an example use case ('does Claude know about us as well as our competitors?'), making the purpose unmistakable.

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

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

It explicitly mentions the tool is 'Useful for competitive AI-marketing audits' and implies a multi-entity scenario (your brand + N competitors). It references ai_visibility_check as the underlying probe, hinting at the single-entity alternative, but does not explicitly state when not to use this tool or name other alternatives like compare_entities.

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

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

The description goes well beyond the annotations by explaining it fans out across external services, publishes a specific return shape, and discloses graceful degradation and timeout behavior: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out'. It also notes the v1 scope limitation. No contradiction with the read-only/idempotent/harmless 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 structured with a clear opening sentence, then usage, output shape, ecosystem scope, and failure behavior. Each sentence contributes new, actionable information without fluff. It is longer than average but earns its length by covering critical operational details like latency and partial failures, making it well-organized and front-loaded.

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

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

With no output schema, the description compensates by listing the exact summary fields returned (is_latest, license, published_at, etc.), per-advisory details, links, and alternative versions. It also covers latency, timeout, and source failure behavior. For a composite tool across two external APIs, this is comprehensive enough for an agent to invoke it correctly and interpret responses.

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 fully documents both parameters (package name, version) with examples and defaults, giving 100% coverage. The description adds context on use cases and output, but does not add new meaning to the parameters themselves. With baseline 3 for full schema coverage, the description provides slight extra context (e.g., scoped packages accepted) already covered by schema, so no higher score is justified.

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 composite purpose: 'should I add this npm package to my project' check, and explicitly names the data sources (deps.dev and bundlephobia) and what they provide. It clearly distinguishes itself from sibling tools by focusing on npm dependency risk/impact evaluation, a unique niche among the listed tools.

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

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

The description gives explicit usage triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clarifies ecosystem boundaries: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which steers the agent to alternative tools for non-npm packages.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds an authentication requirement (bsky_handle and bsky_app_password) and specifies the returned fields, going beyond the annotations to explain operational context.

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

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

The description is two sentences with zero fluff. It front-loads the core purpose and then gives the auth requirement. The minor missing space after 'content.' does not detract from the structure or 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?

The tool is simple (2 params, 1 required) and has an output schema, so the description doesn't need to explain return values. It covers purpose, auth requirement, and general return contents. However, it omits any mention of rate limits or sorting, which could be useful in edge cases, but is not essential for basic 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 description coverage is 100% (query and limit are fully documented). The description adds little beyond what the schema already provides, merely restating the query as 'keyword or phrase' which mirrors the schema's 'Search query'. Baseline 3 is appropriate since 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 it searches Bluesky posts by keyword or phrase, and itemizes the return fields (author handles, timestamps, engagement metrics, content). This distinguishes it from sibling tools like get_posts or get_thread, which retrieve posts by ID or handle.

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 specifies a prerequisite (bsky_handle and bsky_app_password in the gateway URL) which is useful context, but it does not explicitly state when to use this tool versus alternatives, nor any exclusions. Usage is implied by the nature of a search tool, but no when-not guidance is given.

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 the annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character cap with truncation flagging, and that each passage includes character offsets for verification. These details help the agent anticipate output and edge cases, which the annotations (readOnlyHint, idempotentHint) do not cover.

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

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

The description is front-loaded with the core purpose in the first sentence, then expands with usage context and technical details. Every sentence provides useful information without redundancy, achieving a strong balance between thoroughness and 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?

Since there is no output schema, the description compensates by clearly stating the return format (top-N passages with character offsets and similarity scores). It also covers limit scenarios (truncation with flagging), integration with a sibling tool, and the rationale for using it, making it complete for agent decision-making.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for 'text' (SEC 10-K body, article, tool result) and for 'query' (natural-language examples like 'supply-chain risk'), which helps the agent craft effective inputs. It does not add much for 'limit' beyond 'top-N', but the schema already explains that.

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 the tool's function with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly explains the input (text + query) and output (passages with offsets and similarity), and distinguishes itself from sibling tools like ask_pipeworx_grounded by operating on already-retrieved text.

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

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

The description explicitly states when to use it: 'Use when the record is too big to cram into the prompt.' It also positions the tool as a complement to ask_pipeworx_grounded, providing clear context for its role in a workflow. This is direct guidance for agent selection.

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

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

The description adds extensive behavioral detail beyond annotations: requires authenticated Pipeworx account, webhook signing secret returned once, auto-disable after 10 failures, SMS verification and daily cap, and always-on feed. Fully consistent with readOnlyHint=false and idempotentHint=true.

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

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

The description is long but information-dense; every sentence adds value. However, it could be slightly more concise by separating type-specific examples into a table, but the current structure is clear and front-loaded.

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

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

Handles the tool's complexity well: multiple subscription types, nested params object, optional delivery channels, auth requirements, and webhook callback behavior are all explained. Even without an output schema, the description clearly states return values and edge cases.

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

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

Although schema coverage is 100%, the description significantly enriches parameter meaning with concrete examples (e.g., items:["5.02"], topic:"fed", series_id:"UNRATE"), delivery channel constraints, and webhook behavior details. It goes far beyond the 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 clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes itself from sibling tools like list_subscriptions and recent_alerts by focusing on creation and proactive delivery.

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

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

Provides clear context on prerequisites (OAuth account) and delivery channels, and contrasts with pulling via recent_alerts. However, it doesn't explicitly name alternative tools or state when not to subscribe, so it stops short of full 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond this by describing the output structure (category-bucketed example questions with exact tool+argument shape), the source (live catalog), and the behavior of omitting vs passing topic. It effectively communicates what the agent can expect without an output 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 a single dense paragraph that front-loads example queries, then explains the return payload, parameter behavior, and usage context. Every sentence earns its place: no filler, no repetition of schema details, and each clause adds a distinct piece of information. It is appropriately sized for the tool's complexity.

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

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

Given the tool has an optional parameter, returns a complex categorized structure, and serves as an onboarding guide, the description covers all essential aspects: purpose, usage timing, return value shape, parameter semantics, and relationship to sibling tools. It even explains what the output contains (category-bucketed questions with tool+argument shape) despite the absence of an output schema, making it 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?

The schema already provides 100% coverage for the single optional 'topic' parameter, describing its allowed values. The description adds semantic depth by explaining the behavioral difference between omitting it ('full spread') and passing it ('highly focused'), plus giving concrete examples like 'finance', 'pharma', 'betting' that map to the schema's list. This enriches the parameter's meaning beyond the schema 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 explicitly states the tool's purpose as 'the onboarding entry point' that returns 'category-bucketed example questions' with 'exact tool + argument shape' for each. It uses specific verbs like 'Returns' and 'Use this FIRST', clearly distinguishing it from sibling meta-tools (e.g., ask_pipeworx, entity_profile). The many example query phrasings make 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 provides explicit context: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains how to vary usage with or without the topic parameter. However, it does not explicitly state when NOT to use it (exclusions), only implying that it is for initial orientation rather than ongoing use.

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

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

The description discloses that the operation is a soft delete (deactivation) and preserves historical events, which adds valuable context beyond the annotations (idempotentHint, destructiveHint). It also mentions ownership enforcement, which sets behavioral expectations. Since annotations already cover safety profile, the description provides supplementary benefit.

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

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

The description is two sentences long, front-loads the action, and each sentence provides necessary information without waste. It's concise and well-structured.

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

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

For a simple one-parameter tool with no output schema and decent annotations, the description covers purpose, ownership, and the deactivation effect. It also ties to related tool recent_alerts, making it contextually complete.

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

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

Schema coverage is 100% with a clear description of the id parameter ('returned by subscribe'). The description simply says 'by id' and doesn't add new parameter semantics beyond the schema. Per baseline, a 3 is appropriate because the schema does the heavy lifting.

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

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

The description uses the verb 'Cancel' with the specific object 'subscription by id', making the tool's purpose immediately clear. It also distinguishes itself from sibling tools like subscribe and list_subscriptions by indicating this is the cancellation counterpart.

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 indicates the primary use case (cancel subscription) and adds an important condition (only own subscriptions). It doesn't explicitly mention alternatives, but the ownership constraint and deactivation behavior provide sufficient guidance. There are no exclusions or when-not-to-use instructions, but the context is evident from sibling tool names.

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

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

The annotations already flag read-only, open-world, idempotent, and non-destructive, so the description doesn't need to repeat those. It adds vital behavioral context, especially the IMPORTANT warning distinguishing could_not_verify (check never happened, not evidence) from unsupported (no source coverage), plus the return contract (verdicts, actual value with citation, reasoning).

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 a simple two-liner but every sentence adds useful information: trigger phrasing, usage directive, routing, return verdicts, error semantics, and the multi-call consolidation. It is front-loaded with recognizable examples and structured logically, though it could be tightened slightly.

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 results; it lists the full verdict enum, the citation-bearing value, and reasoning. It also covers operational nuances (financial fast path, fallback pipeline, error semantics) and even quantifies the multi-call replacement, making the tool fully self-contained for an agent.

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

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

Schema description coverage is 100%, with both claim and tolerance_pct already well explained. The description adds no parameter-level detail beyond the schema; it only mentions 'exact percent-delta math' in passing, so it earns the schema-coverage baseline of 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 trigger phrases ('Is it true that…' / 'fact check') and states the core function: natural-language claim verification against authoritative sources. It distinguishes the tool by specifying both the financial fast path and the general grounded pipeline, making it clear this is a specialized verifier rather than a generic search/ask tool.

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

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

It explicitly tells the agent when to use it ('Use whenever the agent needs to check whether something a user said is factually correct') and covers routing by claim type. It does not name alternative sibling tools or state when-not-to-use, so it stops short of the full 5-point bar.

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