Lemmy

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds meaningful behavioral context: the default free model, the BYO-key cost implication for Anthropic, and the structured return format, all of which go beyond the 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 compact and front-loaded: it opens with the core function, then key operational detail, then output, then use cases. No 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?

Despite lacking an output schema, the description explains the exact return fields per model and the combined view. It covers the tool's scope, inputs, outputs, and use cases, making it self-sufficient 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 coverage is 100%, so the schema already documents all four parameters. The description adds value by explaining the relationship between `_apiKey` and the `models` array (only needed for Anthropic, direct billing) and the default model behavior, which is not fully clear from the schema alone.

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

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

The description clearly states a specific action ('probe'), the resource ('one or more LLMs'), and the output ('score visibility 0-100 per model'). This distinguishes it from sibling tools like ask_pipeworx which answer questions rather than score visibility.

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') that guide when to invoke it, though it does not name alternatives or exclusions.

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

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

Annotations already disclose read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context on routing to 5,529 tools, filling arguments, returning structured answers with citation URIs, and performance ('one fast call'). 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 long but front-loaded with the key directive ('PREFER OVER WEB SEARCH') and organized with examples and escalation guidance. Some redundancy exists (listing many domains in two places), but each sentence contributes to usage clarity. Not quite a 5 due to minor verbosity.

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 no output schema, the description explains return format (structured answer with citation URIs). It covers what types of questions to use, provides examples, and mentions tier availability. Lacks explicit failure mode info, but overall complete for a well-annotated tool.

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

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

Schema coverage is 100% and all parameters are aliases for the same 'question' field, well documented in the schema. The description adds examples but no new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states this is the default entry point for factual questions, with a specific verb ('ask') and resource ('Pipeworx'). It explicitly distinguishes itself from siblings by naming alternatives (ask_pipeworx_grounded, deep_research) and positioning itself as the general-purpose 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?

Provides explicit 'PREFER OVER WEB SEARCH' guidance, lists trigger phrasings ('what is', 'look up', etc.), gives concrete examples, and names when to step up to alternatives. This is exemplary usage guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses its experimental nature, that candidate routing improvements may be enabled live, and that currently no candidate is active so it matches ask_pipeworx. This adds useful context about potential variability, though it could further detail what happens when a candidate is active.

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

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

The description is five sentences long but every sentence earns its place, covering the beta status, current equivalence, usage instruction, comparison purpose, and reassurance that it is a full working router. It is front-loaded with the core identity and remains tightly structured 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?

For a complex tool (universal router with 5,529 tools) and no output schema, the description is complete: it establishes the tool's role, current state, usage, comparison mechanism, and response shape equivalence. It provides enough context 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%, so the baseline is 3. The description mentions 'same arguments' as ask_pipeworx but does not add parameter-specific meaning beyond the schema's detailed alias descriptions. This is sufficient since the schema carries the full semantic weight.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with 5,529 tools, same arguments, and same response shape. It explicitly distinguishes itself from the stable sibling by its experimental routing improvements and current state of matching ask_pipeworx exactly, making the purpose and scope unambiguous.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router for merging decisions. It also clarifies that there is no fallback behavior and that it is a fully functional router, preventing misuse as a fallback tool.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behaviors: an extra LLM call, a structured success/refusal response shape, specific refusal reasons (not_in_source, no_tool_match, etc.), and that it uses only the tool result. This adds significant context and 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 front-loaded with the core purpose, then details the return shape, refusal behavior, and usage guidance. Every sentence earns its place; it is informative without being wordy or redundant.

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

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

Despite no output schema, the description fully documents the return value shape, success and refusal cases, cost implications, and alternatives. Combined with rich annotations and a simple single-question parameter set, this is complete for an AI agent to correctly select and invoke the tool.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description adds context about how the question is used (routing, argument filling) but no parameter-specific meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb+resource+scope: a hallucination-resistant answer mode that extracts answers only from tool results. It explicitly distinguishes from ask_pipeworx by describing the same routing but an added extraction step, and from other siblings like validate_claim by focusing on ground-to-source answer extraction.

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: for high-stakes, quotable, or actionable answers where facts must not be invented, with concrete examples (financial, legal, medical, public statements). Also gives an alternative: prefer ask_pipeworx for casual lookups due to the extra LLM call.

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

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

Even with strong annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true), the description adds substantial behavioral context: parallel fan-out, resolver contract with confidence levels, safety short-circuit on low confidence, closed-market statuses, illiquid wide-spread flags, and cancellation-rule parsing. This far exceeds the annotations and gives agents crucial expectations about edge cases and return semantics.

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 uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) and front-loaded purpose. However, it is quite long and contains many examples and edge-case details that, while useful, could be trimmed or moved to an output schema. It earns a 4 for clear organization but loses a point for verbosity.

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 (classification, parallel fan-out, resolver disambiguation, safety mechanisms) and the absence of an output schema, the description is remarkably complete. It covers response shapes, resolver contract, parent-event extraction, news fallback fields, statuses for low-confidence and closed markets, spread warnings, and cancellation-rule risk—all essential for correct use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not significantly add parameter-level semantics beyond what the schema already provides (market input formats, depth options, include_raw toggle). The fan-out examples partly illustrate output behavior but don't enrich parameter meaning enough to justify a higher score.

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 distinguishes from siblings like polymarket_arbitrage or polymarket_edges by framing the tool as the general-purpose bet research entry point and giving explicit user intents ('should I bet on X', 'what does the data say about Y').

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 ('Use for should I bet...') and detailed fan-out examples showing when to invoke. However, it doesn't explicitly state when not to use this tool or name alternatives like ask_pipeworx or deep_research, so it lacks the full when-not/alternatives contrast needed for a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by specifying return fields and scope, but does not disclose pagination behavior, sorting defaults, or rate limits. It adds moderate context 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?

Two sentences pack purpose, scope, return fields, and use case with zero filler. The description is front-loaded with the action verb and completely avoids redundancy.

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

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

With 8 optional parameters and no schema descriptions, the description leaves too much unspecified. The output schema exists but doesn't help with invocation, and no guidance is given on how to combine parameters to achieve a particular thread or depth. The tool is under-described for its 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 0% and there are 8 undocumented parameters. The description only hints at 'post or thread' but never explains parameters like post_id, parent_id, instance, community, max_depth, sort, limit, or page. The agent cannot infer parameter meaning or required combinations from this 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 uses a specific verb ('List') and resource ('Lemmy comments under a post or thread'), states returned fields, and names the use case. It clearly distinguishes this from siblings like 'posts' or 'post' by focusing on comments/discussion threads.

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

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

It explicitly says 'Use to read discussion threads', giving clear context. It doesn't list exclusions or name alternatives, but the sibling list provides enough contrast that an agent can infer when to choose this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context by specifying the exact return fields (name, description, subscriber count) and sort/filter capabilities, going beyond the annotations.

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

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

Two efficient sentences, front-loaded with the core action. Every clause adds value (default instance, sort/filter options, return fields) with no redundant wording.

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 list tool with an output schema, the description covers the essential aspects: purpose, default instance, sort/filter options, and return fields. It could mention pagination behavior of page/limit, but the output schema plus annotations make it sufficiently complete. Not perfect, but solid.

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

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

Schema has 0% parameter descriptions, so the description must compensate. It explains the semantics of 'sort' (Active/Hot/New/TopMonth/etc.), 'type_' (All/Local/Subscribed), and 'instance' (default lemmy.world), but does not address 'page' or 'limit', which are non-obvious. Partial guidance, so baseline 3.

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

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

The description clearly states the tool's function: 'List communities on a Lemmy instance', with specific sorting and filtering options. It distinguishes from the sibling tool 'community' (singular) by explicitly pluralizing and listing features.

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

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

Provides clear context for when to use the tool (listing communities), including default instance and available filters/sorts. However, it does not explicitly mention alternatives or exclusions, such as when to use 'community' instead.

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

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

Annotations already establish read-only and idempotent behavior. The description adds value by stating what the tool returns (description, icon, subscriber count, moderators) and clarifying it fetches from a specified instance. It does not mention error cases, but the added context is sufficient for a simple read operation.

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 purpose, includes examples, and summarizes return fields. Every word contributes meaning with no fluff.

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

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

The tool is low-complexity: it fetches metadata for one community. The description covers purpose, input semantics, and key output fields, while annotations cover safety. The output schema exists, so the description is complete enough for an agent to invoke and interpret the tool correctly.

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

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

The schema provides no parameter descriptions, so the description carries the full burden. It clearly explains that name_or_id can be a community name like 'asklemmy' or a numeric id, and that instance is the source instance. The schema examples reinforce this, making the parameter semantics unambiguous.

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 ('Fetch metadata') and clearly identifies the resource: a specific Lemmy community by name or numeric id from a specified instance. This distinguishes it from the sibling 'communities' tool by focusing on a single community's metadata.

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 clear context for when to use the tool (fetching a specific community's metadata) and gives input format examples. It does not explicitly exclude alternatives like 'communities' for listing, but the singular/plural distinction strongly implies the appropriate use case.

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

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

Goes beyond the annotations by detailing what data is fetched (10-K revenue, net income, cash, long-term debt, FAERS counts), how off-calendar fiscal years are handled, that results are sorted by primary metric, and that output includes paired data and pipeworx:// citation URIs. This is rich behavioral context consistent with readOnlyHint.

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

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

The description is dense yet efficient, front-loaded with examples and core behavior. Every sentence adds value, including the 'off-calendar fiscal years' edge case and the 'replaces 8–15 sequential lookups' performance note. 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?

Even without an output schema, the description fully explains the return format (paired data + citation URIs), sorting behavior, and data sources for both entity types. It also addresses edge cases like fiscal year variation, making it self-sufficient for an agent to select and invoke the tool correctly.

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

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

The description significantly enriches the schema's parameter documentation. It explains the 'type' enum with detailed data source differences and clarifies 'values' formats (tickers/CIKs vs drug names). The schema already has 100% coverage, but the description adds substantial meaning beyond the basic property descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with explicit trigger phrases like 'Compare X and Y' and 'rank these companies.' It distinguishes itself from sibling tools by emphasizing it should be preferred over sequential single-pack 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?

Provides explicit guidance on when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists concrete example queries. It also differentiates between company and drug types, telling users exactly what each type pulls, effectively covering 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?

Discloses rich behavioral details beyond annotations: account requirements, paid tier for 'thorough', decomposition into facets, parallel routing, findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] for unanswered facets, never-invent guarantee, contradictions[] for standard/thorough, second-hop iteration, semantic excerpting, and expected latency. This far exceeds what annotations imply and contains no contradictions.

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

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

The description is long but every sentence carries unique, non-redundant information. It is front-loaded with the critical constraint (account required) and then systematically covers behavior, output, use cases, and limitations. The density is appropriate for the tool's complexity; no filler or repetition.

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

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

Given the tool's complexity and lack of an output schema, the description fully explains what the caller should expect: a findings packet with specific fields, gaps[], contradictions[], hop field, citation_uri behavior, latency ranges, and differences between depth levels. It also covers edge cases (breaking news, single lookups, signed-out users), making it essentially 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?

Though schema coverage is 100%, the description adds substantial meaning to both parameters. It explains depth values behaviorally (quick=3 facets single-hop, standard=5 with gap recovery + contradictions, thorough=8 paid with iterative hop) and clarifies that question accepts broad/multi-part natural language. This goes well beyond the schema's terse descriptions.

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

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

The description opens with a clear verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explicitly differentiates from open-web search and sibling ask_pipeworx. It states exactly what the tool does and how it differs from alternatives.

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 and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also names the fallback if not signed in. This is textbook usage differentiation.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds valuable behavioral context: returns top-N tools with names, descriptions, and full input schemas with curated examples, and that no second schema lookup is needed. This goes beyond the annotations without contradicting them.

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

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

Three sentences: purpose, usage context, and return behavior. Each sentence earns its place with no fluff. The most critical 'Call this FIRST' instruction is included. Well-structured and appropriately sized.

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

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

For a tool discovery meta-tool with no output schema, the description sufficiently explains return values (top-N tools with schemas and examples). It lists supported domains and advises when to call first. Combined with complete schema coverage and annotations, the description is fully adequate for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the concept of 'top-N' and 'full input schemas' but does not deepen parameter meanings beyond what the schema already provides (query is a natural language description with aliases, limit controls count). It meets the baseline but doesn't exceed it.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the action (find/discover), the resource (tools), and differentiates from siblings like 'search' (which searches data, not tools). The list of supported domains and 'Call this FIRST' reinforces its distinct role.

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: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and a direct instruction, though it doesn't name alternatives, the guidance is unambiguous.

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

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

Beyond the readOnly/idempotent annotations, the description reveals concrete behavioral details: it fans out across multiple sources, returns specific fields (cik, filings with URIs, fundamentals, patents, news, LEI), notes the USPTO PatentsView sunset with soft-fail behavior, and explains the GDELT→GNews fallback. This transparency exceeds the annotations.

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

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

The description is a single dense paragraph that packs a lot of information, but the opening example queries could be trimmed. Still, each section (usage, return fields, limitations) earns its place and the structure is scannable with semicolons.

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

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

With no output schema, the description fully enumerates the return payload: CIK, company name, recent filings with URIs, fundamentals sorted by period, patents, news, and LEI. It also covers caveats (name support, patent API sunset) and the parallel call performance, making it a complete guide for an AI agent.

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

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

The input schema already provides 100% coverage for both parameters, including enum values and examples. The description essentially repeats the schema's parameter guidance without adding additional semantic nuance, so it meets the baseline but doesn't elevate it.

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

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

The description clearly states the tool's function: producing a full cross-source profile of a US public company via one parallel call. It uses specific verbs like 'profile', 'brief', 'rundown' and explicitly contrasts with single-pack lookups, distinguishing it from sibling tools.

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

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

It explicitly instructs to prefer this tool over chaining separate SEC/XBRL/news lookups for holistic requests. It also provides an exclusion: names are not supported and directs to resolve_entity first, an explicit alternative.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about what gets destroyed (previously stored memory) and why (clearing sensitive data), going beyond the annotation flags. 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 sentences: the first states the action, the second gives usage guidance. No wasted words, front-loaded and highly efficient.

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

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

For a simple 1-parameter tool with rich annotations, the description fully covers purpose, usage, and relational context. No output schema exists, but the tool is simple and the description does not need to explain return values.

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 'key' parameter is clearly described as 'Memory key to delete'. The description only repeats 'by key' without adding extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description states 'Delete a previously stored memory by key' with a specific verb (Delete), resource (memory), and scope (by key). This clearly differentiates from sibling tools like 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?

Explicit usage guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also recommends pairing with remember and recall, giving clear context for when to use this tool vs 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?

The description discloses the tool's behavior beyond annotations: it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also describes the output as a 'single text blob ready to drop at site-root/llms.txt.' Annotations already cover readOnly and idempotent hints, so this adds useful process detail, though it lacks edge-case information like failure handling.

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 that front-load the purpose, then explain the process and output, followed by a compact use-case list. Every sentence earns its place with no fluff, making it highly concise and well-structured.

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

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

For a simple tool with only two parameters and no output schema, the description is complete: it explains the output format ('a single text blob'), the use cases, and the process. An agent has enough context to select and invoke it correctly without needing additional details.

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

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

Schema coverage is 100% with both 'url' and 'max_links' already well-described in the input schema. The description adds minimal extra meaning (e.g., 'key links' hints at max_links' purpose), but the schema carries the heavy lifting. This aligns with the baseline 3 for high schema coverage.

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

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

The description clearly states a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It explains the output format and the extraction process, distinguishing itself from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on producing the actual llms.txt file rather than just checking or auditing AI presence.

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

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

The description provides a 'Useful for' list with three concrete scenarios (client indexing, own project drafting, competitor auditing), offering clear context on when to use. However, it does not explicitly state when not to use or name alternative tools, so it stops short of full alternative/exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful context by listing the returned fields (id, type, params, etc.). It does not contradict annotations and provides additional behavioral clarity.

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. The first states the action and return fields; the second gives practical usage. Every word earns its place with no redundancy.

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

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

For a simple read-only list tool with one optional parameter and good annotations, the description is complete. It covers what is returned, the scope (caller's subscriptions), and typical use cases, so an agent can invoke it correctly without gaps.

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

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

The only parameter (include_inactive) has a complete schema description, so the schema covers it fully. The tool description adds no extra semantic information about the parameter, warranting the baseline score 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 clearly states 'List the caller's active subscriptions' with a specific verb and resource, and differentiates from sibling subscribe/unsubscribe tools. It also lists the return fields, making the purpose unambiguous.

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

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

The description provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for when to use, though it does not mention when not to use or name alternatives explicitly.

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 behavioral traits well beyond the annotations. It explains the claim_token mechanism, rate limiting ('5 per identifier per day'), that it is free and doesn't count against quota, and that the team reads digests daily. These are valuable operational details not available from annotations (all false) or the 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 fairly long but well-structured and front-loaded. Each sentence carries essential information: purpose in the first sentence, usage conditions, exclusions, token handling, and limits. No sentence is wasted, but the length is more than the minimum needed for a feedback tool.

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

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

The description is complete given the complexity. It covers all use cases, the claim_token flow, rate limits, and the connection scope. There is no output schema, but the description clearly states what the tool returns (claim_token and later status). The nested context object is adequately explained in the schema, and the description does not need to repeat it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics beyond the schema: it instructs to 'describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and explains the claim_token usage in detail. This elevates it above baseline, though not to a 5 since schema already covers the basic types.

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 action and target: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It goes on to specify the exact types of feedback (bug, feature/data_gap, praise) and distinguishes itself from sibling tools by stating it is solely for tools served by this Pipeworx connection, not other MCP servers.

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

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

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This fully addresses when to use this tool versus alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds valuable behavioral context: it mentions the data source (CF analytics-engine), that it contains no PII, and that results are cached for 5min-1h depending on window. This goes beyond what annotations provide.

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

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

The description is front-loaded with the core question and returns statement, followed by a concise list of use cases and a note on data origin and caching. Every sentence adds value, though the list makes it slightly longer than strictly necessary.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description adequately covers what it returns (top tools, top packs, total call volume, "(pack, tool, count)"), the data source, and the use cases. It's complete enough for an agent to invoke it correctly.

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

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

The schema fully covers the only parameter 'window' with enum values and a clear description of how shorter vs longer windows affect results. The main description only repeats the options without adding new semantics beyond the schema, so baseline 3 applies.

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

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

The description opens with a clear question, "What other AI agents are calling on Pipeworx right now", then states it returns top tools, top packs, and total call volume. This is a specific verb+resource+scope that clearly distinguishes it from siblings like discover_tools or search.

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

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

The "Useful for" section lists three concrete scenarios, giving clear context for when to use the tool. It doesn't explicitly exclude alternatives, but the use cases are specific enough to guide an agent on when this is appropriate.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: FILL CHECK details (theoretical vs realizable edge, thin_legs, 'do not trade it' if realizable_edge_pp <= 0), PARTITION FILTER placeholder rules, SEMANTIC ANCHOR Jaccard threshold, and the exact response structure. No contradiction with annotations.

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

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

Although long, every sentence is information-dense and labeled with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). The structure makes it easy to scan for relevant details, and the length is justified by the tool's complexity (3 modes, filters, response fields, fill check). 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?

This is a high-complexity tool with no output schema, so the description carries the full burden of explaining return values and caveats. It covers all modes, response fields (opportunities[], partition_check{}, fill_check), filtering logic, and edge cases. It even points to a sibling tool for related but different functionality. Nothing important is left unstated.

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

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

Schema description coverage is 100% and each parameter has good schema descriptions, but the tool description goes much further by providing concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), clarifying fallback behavior with no args, and explaining what each mode does with the parameter. This adds meaning far beyond the schema.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and contrasts with sibling tools like polymarket_fill_risk and polymarket_edges by stating exactly what it does and what it doesn't (e.g., fill check vs custom sizing).

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool for related needs: 'For custom sizing use polymarket_fill_risk.' This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint and destructiveHint, but the description adds substantial behavioral context: 1h caching at KV level, response segmentation, model-family calculation details, a 24h-move warning, diagnostics funnel, placeholder-slug filtering, and an explicit caveat about Fed-signal unreliability. This is far beyond what annotations provide and contains no contradictions.

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 very long but well-structured with clear section labels (e.g., 'FIVE MODEL FAMILIES', 'TRADEABLE-EDGE KNOBS', 'RESPONSE TOP-LEVEL'). Every sentence carries unique technical information, so there is no unnecessary filler. It earns a 4 rather than 5 because the length may be overwhelming for an agent and could have been slightly trimmed while preserving key 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?

With no output schema, the description fully compensates by detailing the response top-level (by_segment, fed_candidates, _diagnostics), empty-segment reasoning, caching, and limitations. It covers all nine knobs with practical examples and defaults, making the tool usable correctly 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?

Although schema coverage is 100%, the description adds critical semantic nuance: slippage rationale, tradeable-edge filters, and the key distinction that min_kelly doesn't apply to partition arbs (min_partition_leg_kelly does). It explains how knobs interact and what happens when filters are too strict, going well beyond the schema's plain parameter names.

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+purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement and the 'what should I bet on today' use case.

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 the intended usage context ('Built for "what should I bet on today"') and provides practical guidance on knobs (min_liquidity, max_spread_pp, category_filter, min_partition_leg_kelly). It doesn't name alternative tools, so it stops short of a full 5, but context is clear and exclusions are implied (e.g., Fed bets are excluded from ranking).

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

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

Annotations already indicate read-only/idempotent, but the description adds rich behavioral context: data from daily snapshots, 60-day TTL, cache-miss behavior explaining gaps, and decay computed on daily closes rather than intraday. Discloses response semantics and limitations.

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

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

Long but well-structured: front-loaded purpose, then args, response structure, and limitations. Every section adds value, though some details could be trimmed without losing meaning.

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

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

No output schema, yet the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and caveats (TTL, gaps, daily closes). Complete for a complex telemetry tool.

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

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

Schema coverage is 100% and the description largely repeats the schema (defaults, max). Adds minor context about 'window' being a snapshot family, but not substantial new parameter meaning beyond what the schema already provides.

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

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

States a specific purpose: tracking edge persistence and decay across daily snapshots, answering 'how long has this edge existed and is it shrinking?'. Clearly distinguishes from sibling polymarket_edges by focusing on temporal telemetry rather than current edges.

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?

Implies usage for assessing edge age and decay with a practical example (fresh vs old wide edges). Does not explicitly mention when not to use or alternative tools, but the context is clear.

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

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

Beyond the readOnly and idempotent annotations, the description discloses behavioral details: walks the ladder, returns top-of-book and VWAP, identifies thin legs, and warns about forced directional risk. It also explains that this is a pre-trade check that does not execute trades, aligning with readOnlyHint and adding significant context about what the tool computes.

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, using 'REQUIRES,' 'SINGLE-MARKET,' and 'BASKET' as clear organizers. Every sentence adds information, though the length approaches the upper limit of conciseness. It is front-loaded with core purpose and maintains logical flow.

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

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

With no output schema, the description fully enumerates return values for both modes, including edge cases like thin_legs and forced_directional_risk. It covers prerequisites (market or event), side handling, size interpretation, and the risk of partial fills, making it comprehensive for both modes.

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 parameters are already documented, but the description adds relational semantics: it clarifies that market and event are mutually exclusive modes, and explains how size_usd is interpreted differently in each mode (max spend vs. target proceeds vs. settlement notional). Side defaults in basket mode are also contextualized. This goes beyond a simple restatement of the schema.

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

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

The description opens with a specific verb+resource phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges as the tools this should precede, making its unique role in the workflow 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?

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also distinguishes single-market vs. basket modes with concrete conditions, and explains why partial fills are dangerous, giving a clear 'when to use' directive.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: it explains the compatibility_warning cases, temporal_alignment, skipped_cross_type/subtype counters, and when spreads are meaningless. It even warns that real spreads are rarer than the shortcut list suggests, which goes well beyond the structured annotations.

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

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

The description is long but every sentence adds unique value, covering modes, response format, and safety fields with uppercase labels. The opening sentence is a clear summary. It is appropriately sized for the tool's complexity, though it is dense and could be slightly more scannable, preventing a perfect score.

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

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

With no output schema, the description takes full responsibility for explaining the return payload: it details leg-by-leg prices (0-1), spread calculations, and the safety fields (compatibility_warning, temporal_alignment, skipped counters). It also covers edge cases like non-equivalent bet shapes and temporal mismatches, making it complete for an analysis tool with 3 optional 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?

The input schema already has 100% coverage with descriptions and examples for each parameter, so the baseline is 3. The description adds semantic value by explaining how the parameters interact in two modes (topic auto-fetch vs explicit overrides), and clarifies the meaning of the response fields in relation to parameters. This elevates it above baseline but doesn't add deep format-specific detail 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 computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific verb ('Cross-venue spread') and resource. It differentiates from sibling tools like polymarket_arbitrage by focusing on the two-venue comparison and explaining the two modes (topic shortcuts and explicit pairings).

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

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

The description provides explicit guidance on when to use topic shortcuts vs explicit event identifiers, and warns that most pre-mapped topics are not tradeable, saying 'pre-mapped ≠ tradeable.' It also explains how to interpret compatibility warnings and temporal alignment, but does not explicitly name alternative tools for when this tool is inappropriate, so it misses a clear 'when-not' statement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by stating the default instance and enumerating the return fields (title, body, author, score, comment count, and community), which goes beyond what annotations provide and does not contradict them.

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

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

The description is a single, focused sentence that front-loads the action and includes only necessary details. Every word earns its place, with no redundancy.

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

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

For a simple fetch tool with two parameters, strong annotations (readOnlyHint, idempotentHint), and a known output schema, the description covers all essential aspects: what it fetches, the default instance, and the returned fields. It is complete and actionable 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?

With schema description coverage at 0%, the description compensates by clarifying that 'id' is numeric and by explaining the 'instance' parameter with a default value (lemmy.world). The examples further illustrate parameter usage, making the semantics clear.

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 'Fetch a single Lemmy post by numeric id' with a specific verb and resource. It distinguishes from sibling 'posts' by emphasizing 'single' post and the numeric id requirement, making its purpose unambiguous.

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

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

The description provides clear context for when to use the tool: when you have a numeric id and need a single post. It specifies the default instance (lemmy.world) but does not explicitly mention alternatives or exclusions relative to sibling tools like 'posts'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by listing return fields (title, body, author, upvotes, comment count) and sort modes, which are not fully captured in annotations. It does not repeat annotation info or contradict it.

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

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

The description is four short, front-loaded sentences. Each sentence conveys distinct information: what the tool lists, sort options, returned fields, and use case. There is no redundancy or filler, making it extremely concise for the information provided.

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 list tool with 6 parameters and an output schema, the description covers the essential aspects: purpose, feed/community source, sort options, and return fields. The output schema handles return structure, so the description doesn't need to explain that. It misses explicit guidance on instance and type_ filters, but the tool is simple enough that the overall description is sufficient.

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

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

Schema description coverage is 50%, with sort, type_, and community having descriptions. The description adds meaning for community ('from a community or feed') and sort ('Active / Hot / New / TopDay / TopWeek / etc.'), but leaves page, limit, and instance semantics unexplained beyond their types. It partially compensates for the gap but not fully.

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 'List' with a clear resource 'Lemmy posts', and details that it works from a community or feed. It distinguishes itself from siblings like 'post' (singular) and 'comments' by focusing on listing multiple posts. Mention of sort options and return fields further sharpens the purpose.

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

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

The description provides clear context by stating 'Use for federated open-source discussion forum content' and implies when to use it for browsing posts from a community or feed. However, it does not explicitly mention alternatives like 'post' for a single post or 'comments' for comment listings, which would have made the guidance stronger.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds meaningful context beyond this: scoping to an identifier ('anonymous IP, BYO key hash, or account ID'), the omitting-key listing behavior, and examples of stored content. This gives the agent a clearer behavioral model without contradicting annotations.

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

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

Three sentences with no fluff. The primary action is front-loaded, and it efficiently includes examples, scoping, and sibling references. Every sentence serves a 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?

For a tool with only one optional parameter and no output schema, the description fully covers both invocation modes (retrieve by key or list all), scoping, and the relationship to remember and forget. There are no significant contextual 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% for the single key parameter, so the description need not compensate. It reinforces the omit-to-list behavior (already in schema) and provides example key names, but does not add significant new semantic information beyond the schema.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes itself from sibling tools by explicitly naming remember and forget as companions, and specifies the exact operation variants.

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 usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' Mentions pairing with remember/forget. Does not explicitly list exclusion cases (e.g., external search), but the intended use is well-defined.

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?

Description contradicts the readOnlyHint annotation by explicitly stating 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a persistent state mutation. Although it discloses the return payload and polling behavior, the contradiction with the read-only annotation is a serious issue.

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

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

The description is three sentences, front-loaded with the core verb and resource, and every sentence earns its place: return payload details, filtering/mark_read semantics, and a pointer to the same feed via HTTP for scripts. No filler or repetition of schema fields.

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 no output schema, the description compensates by disclosing the return payload components (source, citation_uri, raw event payload) and the polling workflow. It covers the key behaviors and points to an external endpoint for non-agent use. However, the annotation contradiction about read-only vs. mark_read creates a completeness gap in the overall tool contract.

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 all 5 parameters (100% coverage), so baseline is 3. The description adds value by providing a concrete type example ("sec_8k"), specifying the ISO timestamp format for 'since', and explaining the effect of mark_read on subsequent calls. It does not add detail for limit or unread_only, but that is already in the schema.

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

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

Description opens with 'Pull fired events from your subscription feed,' a specific verb+resource combination. It further distinguishes the tool by detailing what each alert carries (source, citation_uri, raw event payload) and offers filtering options, making it clear this is the tool for reading recent subscription alerts.

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

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

Provides clear usage context: supports polling, filtering by type/since, and mark_read behavior for incremental reads. However, it only mentions an external GET endpoint as an alternative for scripts/dashboards, not sibling tools, so it lacks explicit when-not-to-use guidance relative to the MCP toolset.

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 safety (readOnly, idempotent, non-destructive), but the description adds rich behavior: parallel fan-out to SEC/GDELT/GNews/USPTO, fallback logic (GDELT preferred, GNews on rate-limits/5xx), PatentsView soft-fail sunset, and return structure. 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?

Dense but efficient. Every sentence serves a purpose, and user-intent phrases front-load the purpose. The fallback explanation is necessary for correct expectations, and the alternative tool pointer is concise.

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 fully specifies return shape (changes[], total_changes, citation URIs) and covers edge cases (soft-fail, fallback). It also names the alternative tool for static profiles, making it self-sufficient for selection.

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 description adds no new parameter meaning. It restates the same formats (ISO or relative) and examples. Slight value in suggesting '30d' or '1m' for typical monitoring, but this is minor.

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 intents ('What's new with X' / 'latest on Y') and clearly defines the tool as a change feed for a company in a recent window. It explicitly contrasts with entity_profile, distinguishing it from a prominent sibling.

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

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

Provides explicit when-to-use guidance via natural language queries and states when to prefer entity_profile instead. This gives clear boundaries without needing to reference every sibling.

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

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

Annotations already certify idempotent and non-destructive, and the description adds meaningful context beyond that: key-value scoping by identifier, persistence differences for authenticated vs anonymous sessions (24h retention). It does not contradict annotations and enriches the behavioral model.

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

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

Three sentences, no wasted words. The main action is front-loaded, and each sentence adds distinct value: what it does, when to use, and how it behaves (session persistence, pairing with recall/forget).

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

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

For a simple two-parameter tool with 100% schema coverage and clear annotations, the description covers all essential aspects: purpose, usage context, persistence behavior, and relationship to sibling tools. No output schema exists, but the tool's return value is not critical for the agent to invoke it correctly.

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

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

The input schema fully documents both parameters (key and value) with descriptions and examples, so baseline is 3. The description only restates that it's a key-value pair, adding little beyond the schema's existing coverage.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later' and clarifies scope across conversation or sessions. It clearly distinguishes from siblings by naming recall and forget as complementary operations.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward...' and gives concrete examples like resolved ticker or user preference. It also tells when not to use it by directing to recall for retrieval and forget for deletion, making the choice clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses that the tool cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, and explicitly reports unresolved identifiers. This adds rich behavioral context that annotations alone do not provide.

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

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

The description is long but information-dense; every sentence contributes useful detail about purpose, supported types, or edge-case behavior. It is front-loaded with examples and core use, though it could be slightly trimmed without losing value.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, fallback behavior, no output schema), the description covers all critical aspects: inputs, output contents, unresolved handling, graceful degradation, and efficiency. It is virtually 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?

Even though the schema describes both parameters, the description greatly enriches them: it explains accepted input formats (ticker, CIK, name for company; brand/generic for drug), the types of identifiers returned, and example values. This goes well beyond the schema's minimal 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 resolves names to canonical identifiers, uses specific verbs like 'resolve' and 'look up', and gives concrete example queries. It distinguishes itself from siblings by focusing on converting names to IDs and explicitly says 'Use FIRST whenever you have a name but need an ID.'

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 guidance: 'Use FIRST whenever you have a name but need an ID.' This is clear context for when to use the tool, but it does not mention when not to use it or name alternative sibling tools, so it misses the full 'when-not/alternatives' criterion.

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

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

Annotations already establish this is a safe read operation (readOnlyHint, idempotentHint). The description adds useful behavioral detail beyond that: it reveals the tool 'probes each entity with ai_visibility_check', explicitly names a sibling tool as an internal dependency, and describes the ranking/return behavior. This transparency about the underlying mechanism is valuable and does not contradict the annotations.

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

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

The description is three sentences with zero filler. It front-loads the core purpose (compare side-by-side), then explains the method (probes with ai_visibility_check), then gives a use case and output summary. Every sentence earns its place.

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

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

For a composite tool with 4 parameters and no output schema, the description is quite complete. It explains the relationship to a sibling tool, what the output looks like (ranked list with score, confidence, signal density), and when it's useful. It doesn't discuss error handling or rate limits, but given the strong annotation coverage and simplicity, this is adequate.

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

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

Schema coverage is 100%, so all parameters are already described in the schema. The description adds minimal semantic value beyond the schema: it frames entities as 'your brand + N competitors' and mentions 'context applied to every probe' (which is also in the schema). This meets the baseline but does not go beyond what the schema already provides.

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

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

The description clearly states the tool's function: comparing AI visibility across multiple entities. It explicitly distinguishes itself from the single-entity sibling ai_visibility_check by describing a side-by-side batch comparison with ranking. The verb 'scan' plus specific resource 'competitor AI presence' makes the purpose unambiguous.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and a real-world question ('does Claude know about us as well as our competitors?'). It implies the tool is for comparing multiple entities rather than a single one, but does not explicitly mention alternatives or exclusions. This is clear context without formal when-to-use/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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it fans out across two external services, discloses partial failure handling (sources_failed on timeout), and warns about a 5-30s delay for first-time bundlephobia measurements. No contradictions.

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: purpose, usage, return contents, scope, and failure behavior each in their own sentence. It is front-loaded with the core purpose and every sentence earns its place given the tool's composite nature. Length is justified.

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

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

Despite no output schema, the description lists the exact summary fields, per-advisory details, links, and alternative versions. It also covers ecosystem scope and graceful degradation. The input schema fully covers parameters, and annotations cover safety—making the description complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%; both parameters (package and version) already have clear descriptions including scoped package format and default behavior. The tool description adds no extra parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb+resource: scans an npm dependency across deps.dev and bundlephobia to answer 'should I add this package' with license, advisories, size, etc. It distinguishes itself as a composite one-call tool and explicitly notes NPM-only in v1, separating it from broader ecosystem tools.

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

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

Explicit usage context is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion by stating non-NPM ecosystems fall under deps.dev:version directly, though it doesn't name a specific sibling tool. This is clear but not a fully explicit alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it is a full-text search, uses lemmy.world as default instance, and supports filtering by type, listing, and sort. This goes beyond the annotations without contradicting them.

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

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

The description is compact—two sentences—and front-loads the primary purpose with the query parameter. Every clause adds relevant information about scope, default instance, and filter options, making it highly efficient.

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

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

The tool has 7 parameters and an output schema, so the description doesn't need to detail return values. It covers the core invocation (required `q`), default instance, and available filters. The main gap is the lack of explicit mention of pagination parameters and alternatives, but for a search tool this is reasonably 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 only 29%, so the description must compensate. It clarifies `q` as the query, `instance` defaults to lemmy.world, and explains `type_`, `listing_type`, and `sort` in prose. While `page` and `limit` are not detailed, they are standard pagination parameters and the description covers the most semantically important fields.

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

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

The description clearly states the tool performs full-text search across a Lemmy instance for posts, comments, communities, or users matching the query `q`. It specifies the default instance and distinguishes itself from sibling tools like `search_within` by covering cross-type search.

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

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

The description implies usage for searching across multiple content types and mentions filtering by type, listing, and sort order. However, it does not explicitly state when to prefer this tool over alternatives like `search_within` or the dedicated `posts`/`comments` endpoints, 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?

The description discloses substantive behavioral details beyond annotations, including the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and the 200K char cap with truncation flagging. It also clarifies return values (passages with offsets and scores). This significantly enriches the agent's model of the tool's runtime behavior.

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

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

The description is dense but every sentence earns its place. It opens with a one-line core definition, then covers usage context, pairing with a sibling tool, and technical behavior. No fluff or repetition; structure front-loads the most important information.

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

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

Even though there is no output schema, the description explains what the tool returns (top-N passages with character offsets and similarity scores) and covers edge cases (truncation flagging). It also provides integration context with ask_pipeworx_grounded. For a tool with this complexity, the description is remarkably complete.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. The description adds contextual value by giving concrete examples of what 'text' should contain (SEC 10-K body, article, tool result) and reinforcing the purpose of the query. This goes slightly beyond the schema's dry parameter descriptions.

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

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

The description clearly states the tool's specific function: 'Semantic search INSIDE a fetched record.' It uses a distinct verb and resource, and explicitly distinguishes it from sibling search tools by emphasizing that it operates on already-fetched text rather than external sources.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt — search_within saves context...' It also names a complementary alternative, ask_pipeworx_grounded, explaining how the tools pair together. This gives the agent a clear decision framework.

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, so the safety profile is clear. The description adds behavioral context by enumerating specific metadata fields returned. It does not disclose potential network latency or rate limits, but for a simple read operation this is acceptable.

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

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

The description is a single concise sentence that front-loads the action and resource, enumerates the key returned data, and states the default. Every word contributes to understanding, with no filler or redundancy.

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

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

Given the tool has an output schema (not detailed here), the description does not need to explain return values. The description covers the tool's purpose, default behavior, and content scope adequately for a simple read-only metadata fetcher. Minor gap: it does not explicitly explain how the 'instance' parameter is formatted, but the example and default mitigate this.

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

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

Input schema has one parameter 'instance' with no description, so schema description coverage is 0%. The description mentions 'default lemmy.world', which implies the parameter is used to specify a different instance, but it does not explicitly state that 'instance' is the domain name of the Lemmy instance. This leaves some ambiguity, though the example in the schema partially compensates.

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 ('Fetch') and a clear resource ('instance-level metadata for a Lemmy instance'), and lists the key contents (site name, description, version, admin info, federated instances list). It differentiates itself from sibling tools that target communities, posts, or search by focusing on instance-level metadata.

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: when you need instance-level metadata. It also provides a default value (lemmy.world), giving context for the common use case. However, it does not explicitly name alternatives or state when not to use it, so it falls short of full exclusion criteria.

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

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

This is an annotation contradiction. The annotations set idempotentHint=true, but the description says 'Create' and 'Returns the new subscription id,' implying that each call creates a fresh subscription—non-idempotent behavior. Although the description richly discloses auth needs, phone verification, SMS caps, and webhook auto-disable, the contradiction with idempotentHint is a fundamental inconsistency that undermines trust.

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

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

The description is notably long but impeccably structured. The first sentence states purpose and return value; the second covers auth requirements; then it systematically details each subscription type with inline examples; finally it explains delivery channels with edge cases. Every sentence carries essential information, and the organization makes the density acceptable.

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 subscription-creation tool with no output schema, the description is remarkably complete. It explains the return value (subscription id), auth prerequisites, delivery options, consumption via a persistent feed, verification steps for SMS, per-day caps, webhook signing, and automatic disabling after failures. This gives an agent all the contextual information needed to invoke the tool correctly in varied scenarios.

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

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

The schema has 100% description coverage, but the tool description goes far beyond schema descriptions. It gives concrete examples for each subscription type (e.g., sec_8k: {items:["5.02"]} = officer change, polymarket_edge: {topic:"fed"}), explains delivery channel options with real formats, and clarifies constraints like SMS must match a verified phone. This adds significant semantic value beyond the JSON schema.

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

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

The description opens with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This distinctly differentiates it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts. It also enumerates supported subscription types, providing concrete scope.

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

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

The description states a key prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also implicitly indicates when to use by explaining delivery channels and how to consume the feed (via recent_alerts or GET registry.pipeworx.io/alerts.json). However, it does not explicitly mention alternatives such as ask_pipeworx or compare_entities, so usage guidance is strong but not exhaustive.

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

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

Annotations already communicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral detail: the output structure (category buckets, exact tool + argument shape), the fact that examples come from a live catalog of thousands of tools, and the optional topic focus. 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 longer than necessary but each component earns its place: trigger phrases for matching user intent, clear output description, calling variants, and usage guidance. It is well-structured and scannable, though the opening list of paraphrases adds minor verbosity.

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

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

Given the simple single-optional-parameter interface and no output schema, the description fully covers what the tool does, what it returns, how to invoke it, and when to use it. It also sets expectations about the meta-tools an agent can learn from it, making it highly 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% since the 'topic' parameter description fully documents allowed values and omission behavior. The description only adds examples (e.g., 'finance', 'pharma') without introducing new meaning, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for an agent to discover what to ask Pipeworx. It specifies the exact resource (example questions organized by category) and differentiates from sibling tools by positioning it as the starting point and by naming the meta-tools it teaches.

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

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

Provides explicit when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do for you') and explains calling patterns (no args vs. topic). It mentions meta-tools as alternatives but does not explicitly list when-not-to-use scenarios, so it falls just short of a full 5.

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

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

Beyond annotations, it adds that ownership is enforced, the row is deactivated (not deleted), and historical events remain available via recent_alerts. This clarifies the deactivation behavior and reinforces idempotentHint and destructiveHint, adding meaningful context beyond the structured annotations.

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

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

Three concise sentences, each adding specific information: the action, the ownership constraint, and the deactivation behavior. No filler, front-loaded with the verb, and every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers the purpose, the constraint, and the side effect (deactivation keeps history). It could mention auth requirements or error behavior, but these are not critical 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 description coverage is 100% for the only parameter 'id', which is clearly described as a uuid from subscribe. The tool description merely says 'by id' without adding new semantics, so it does not add value beyond the schema.

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

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

The description starts with a specific verb 'Cancel' and identifies the resource 'subscription by id', clearly distinguishing from sibling tools like subscribe and list_subscriptions. It also notes the row is deactivated, not deleted, which differentiates from a permanent delete operation.

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 canceling a subscription, and the ownership constraint suggests it's for one's own subscriptions, but it does not explicitly reference alternatives or state when to use this vs. other tools. There is no mention of 'use this when...' or exclusion of other approaches.

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 significant behavioral context beyond the annotations: it explains the meaning of 'could_not_verify' (a failed check, not evidence) and 'unsupported' (no source covers it), and warns against presenting 'could_not_verify' as evidence. It also outlines the return structure (verdict, actual value with citation, reasoning) and the two routing pipelines. These are nuances not captured by readOnlyHint/openWorldHint/idempotentHint.

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 information-dense. It front-loads with example queries to immediately convey intent, then explains the two routes, return semantics, and special-case meanings, followed by a performance note. Every sentence adds value, with no fluff or redundancy.

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

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

Given the tool's complexity (two pipelines, multiple verdict types, error semantics) and lack of an output schema, the description is remarkably complete. It explains the verdict categories, the meaning of 'could_not_verify' vs 'unsupported', the routing logic, and the citation format, covering everything an agent needs to safely invoke and interpret the tool.

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

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

The input schema already provides 100% coverage with detailed descriptions for both parameters ('claim' with examples, 'tolerance_pct' with meaning and default). The description reinforces these with examples and explains tolerance behavior (e.g., 'set 1–2 for hallucination detection'), but it does not add fundamentally new meaning 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 is explicit and specific: it states the tool performs natural-language claim verification against authoritative sources, with examples of queries like 'Is it true that…'. It clearly distinguishes this from generic search by focusing on fact-checking and by describing the two distinct processing paths (SEC EDGAR for financial, grounded pipeline for other facts).

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

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

The description gives clear guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial and other claims, and highlights that it replaces multiple sequential calls. However, it does not explicitly name alternative tools 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.