openalex

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds key behavioral details: the default model is free, using Anthropic incurs external costs, the API key is passed straight through, and it returns per-model and combined response structures. This gives the agent a clear picture of side effects and requirements.

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 purpose, then model-specific and usage details. Every sentence contributes valuable information with no redundancy or filler.

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

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

With no output schema, the description adequately covers the return format ('per-model {score, confidence, signals, raw_response} + a combined view'), default behavior, and common use cases. It provides enough context for an agent to invoke the tool correctly without needing additional documentation.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds slight value by explaining the default model and the necessity of _apiKey for Anthropic, but does not redefine or expand on the schema's 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 starts with a specific verb-resource pair: 'Probe one or more LLMs for what they know about a business / brand / product / topic' and explains the scoring output (0-100 per model). It clearly differentiates from sibling tools like ask_pipeworx or deep_research by focusing on visibility scoring across multiple LLMs.

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 context for when to use the tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains model selection (default Workers AI, optional Anthropic with key) but does not explicitly state when not to use it or name alternative tools.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds context about routing to thousands of tools and returning pipeworx:// citation URIs. It doesn't contradict annotations, but doesn't discuss failure modes or rate limits.

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 earns its place: it front-loads the priority instruction, lists supported domains, explains the routing mechanism, gives examples, and outlines escalation paths. It's dense but not wasteful.

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 central role and many siblings, the description covers purpose, usage, behavior, return format ('structured answer with citations'), tier compatibility, and escalation. No output schema exists, so the description adequately explains what to expect.

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

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

Schema description coverage is 100% with full descriptions for all aliases. The description adds example questions and trigger phrases, but no additional parameter semantics 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 routes questions to 5,564 tools across 1462 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as 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?

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), lists trigger phrases and example queries, and provides clear alternatives for special cases (ask_pipeworx_grounded, deep_research). 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description adds critical context: it is a fully working router (not a fallback), may have live candidate improvements, and currently matches ask_pipeworx exactly since no candidate is active. This discloses the experimental nature and current state, exceeding annotation coverage.

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 deliver substantial information about the beta status, relationship to ask_pipeworx, current candidate inactivity, and usage guidance. Slightly dense but each sentence earns its place; minor redundancy in saying 'this currently matches ask_pipeworx exactly' twice.

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

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

Given the complexity of a router with thousands of tools, the description covers the current state, relationship to the stable version, and response shape (same as ask_pipeworx). It addresses the absence of an output schema by specifying the response shape, making it sufficiently complete.

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

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

Schema coverage is 100% with all 6 parameters described, including aliases for 'question'. The description only says 'same arguments' without adding new semantic detail. This meets the baseline for high schema coverage but does not 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 identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,564 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by noting candidate routing improvements and experimental edge, making the purpose unmistakable.

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

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

Explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router to decide merges. This implies the alternative is to use ask_pipeworx for stable routing, providing clear when-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?

Even with annotations marking readOnly/openWorld/idempotent, the description adds critical behavioral details: the extra LLM call cost, the strict extraction constraint, and the full refusal_reason enum. This goes beyond what annotations provide and helps the agent handle failure modes.

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

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

The description is long but densely informative; every sentence contributes unique value (return format, refusal reasons, cost trade-off, use cases). It is front-loaded with the core purpose. Slightly verbose, but justifiable given the tool's complexity and absence of an output schema.

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

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

Given no output schema, the description thoroughly explains the success and refusal return shapes, the internal routing behavior (5,564 tools, 1462 sources), and when to prefer this over ask_pipeworx. It provides a complete picture for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% (question plus five aliases all documented). The description only reinforces that it takes a natural-language question but adds no syntax or format details beyond the schema. Baseline 3 is appropriate; no deduction needed because the schema carries the load.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly states the tool's distinct value proposition. It differentiates from the sibling ask_pipeworx by explaining that it extracts answers using ONLY what the tool result contains, and mentions explicit refusal behavior. This is a specific verb+resource+scope formulation.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. Also provides an alternative: 'prefer ask_pipeworx for casual lookups.' This gives clear context and exclusions.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds a wealth of behavioral detail: low-confidence matches short-circuit with status:'low_confidence_match', closed markets return 'market_closed_or_inactive', wide-spread markets carry tradeability:'illiquid_wide_spread', and resolution-rule risk explains cancellation rules with quantified EV impact. This far exceeds annotation coverage and provides deep transparency.

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

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

The description is extremely long and dense, though it uses section headers and examples to organize content. It is not front-loaded; the essential use info is in the first sentence, but the many all-caps sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) make it verbose. While each part adds value for a complex tool, overall it is not 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?

Given there is no output schema, the description fully compensates by documenting response shapes (result.market, result.analysis, result.evidence), the resolver contract with match confidence and alternatives, parent_event extractor, news fallback fields, and safety/blocking paths. It covers edge cases like cancellation rules and closed markets, making it complete for the tool's complexity.

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

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

Schema descriptions cover 100% of parameters, including examples, defaults, and explanations. The tool description mainly reiterates that market can be a slug, URL, or question text, but does not add substantive meaning beyond the schema. Baseline 3 is appropriate since the schema carries the semantic load.

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

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

The description clearly states the tool 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket market), the verb (research), and the scope (pipeworx data). It also distinguishes from sibling tools by giving targeted use cases like 'should I bet on X', which sets it apart from polymarket_edges or arbitrage tools.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and provides numerous fan-out examples. It gives clear context for when to use the tool, though it does not explicitly name alternatives or when-not-to-use. This is clear context without exclusions, matching a 4.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds crucial behavioral context: off-calendar fiscal year handling, sorting by primary metric, and return of paired data with pipeworx:// citation URIs. This goes well beyond the annotations.

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

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

The description is dense but well-organized with trigger phrases, a clear directive, and type-specific details. It avoids fluff, though the example list of trigger phrases 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, 2–5 items, parallel execution, no output schema), the description fully contextualizes input constraints, data sources, sorting behavior, and output format. It even quantifies the benefit (replaces 8–15 sequential lookups), making it complete 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% (both type and values have descriptions), so baseline is 3. The description enriches parameter meaning by specifying what each type pulls (company: 10-K financials; drug: FAERS counts, FDA approvals, trial counts) and clarifies the values format with examples. This adds value beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call. It uses specific verbs like 'compare', 'rank', and 'head to head', and distinguishes itself from siblings like entity_profile by explicitly covering multi-entity comparison.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists trigger phrases. It also differentiates between company and drug use cases, making it clear when to invoke this tool versus alternatives.

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

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

The description adds substantial behavioral context beyond the readOnly/openWorld/idempotent/non-destructive annotations: account tier requirements, parallel decomposition, latency expectations, gaps[] behavior (never invented findings), hop/contradiction logic, citation semantics, and excerpting behavior. The openWorldHint is not contradicted; the tool explains its scope precisely.

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 and front-loaded with the critical account sign-in warning at the start. It touches on required setup, usage context, output format, latency, pricing tier differences, and edge cases in a structured way. A few points could be trimmed without loss, but overall each section adds value for a tool of this complexity.

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

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

For a research tool with no output schema, the description sufficiently explains what kind of output the caller will receive: findings packet with verbatim evidence, confidence, source, fetched_at, stable citations, gaps array, hop field, and contradictions for certain depth modes. Complex behavioral edge cases such as unstructured current events, large-record excerpts, and paid depth tiers are all covered.

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 two parameters, so the baseline is met without needing much extra. The description does clarify depth behavior around re-angling gaps, chasing leads, and contradiction scanning, but the depth enum schema already captures most of this. The question parameter is also described in the schema; the description adds only contextual framing about broad/multi-part questions.

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

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

The description clearly states what the tool does: grounded multi-source research over Pipeworx's 1,462 structured data sources, decomposing questions into facets and producing a findings packet with evidence, confidence, citations, and explicit gaps. It also distinguishes itself from siblings by explicitly saying it is NOT open-web search and pointing to ask_pipeworx for single lookups.

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

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

The description provides explicit adoption criteria and alternatives: use it for broad/multi-part structured-data questions, but use ask_pipeworx for simple lookups, breaking news, or current-world topics; also notes signing in is required and that non-signed-in users should use ask_pipeworx instead. Depth guidance and iteration behavior are also explained clearly.

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, and non-destructive behavior. The description adds value by explaining the return format: 'top-N most relevant tools with names, descriptions, and full input schemas' and the convenience of no second lookup. This gives the agent insight into what the tool actually does beyond static 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 long and front-loaded with the core purpose. It includes a lengthy list of domains, which is useful for the agent to understand scope, but the list is somewhat long. Every sentence serves a purpose, with no redundant phrases.

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

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

The description covers the tool's purpose, when to use it, and what it returns, which is particularly important since there is no output schema. It omits details like pagination or error handling, but given the tool's simplicity and the strong annotations, it is sufficiently complete 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 schema fully documents the `query` parameter and its aliases. The description adds no additional parameter details beyond 'describing the data or task,' which is already captured in the schema. Baseline 3 is appropriate; the description does not go beyond the structured information.

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 resource (tools) and the action (browse, search, look up, discover), and distinguishes itself from siblings by emphasizing it returns a list of tools rather than performing a single task. The phrase 'Call this FIRST when you have many tools available' differentiates it as a meta-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?

The description gives clear usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and lists example domains. It also provides an exclusion: 'not just one answer.' However, it does not explicitly name alternative tools, so it stops 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 the readOnly/idempotent annotations, the description discloses that it fans out across multiple data sources, returns specific fields, has a fallback chain (GDELT→GNews), and includes a soft-fail for the USPTO PatentsView API sunset. This gives the agent important behavioral context 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?

The description is dense but purposeful, leading with usage examples and the core purpose before diving into components and limitations. It is somewhat long, but each section serves a functional role—usage guidance, return values, fallbacks, and parameter constraints—so the 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?

Given there is no output schema, the description thoroughly covers return categories (CIK, recent_filings, fundamentals, patents, news mentions, LEI), data source fan-out, and failure behavior. It also addresses parameter constraints and prerequisites, making it complete enough for an agent to invoke and interpret results correctly.

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

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

The schema already provides 100% coverage for both parameters, including the enum for 'type' and detailed description for 'value'. The description reinforces this with examples (AAPL, 0000320193) but adds no materially new meaning beyond what the schema already specifies.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and gives multiple natural-language examples ('Tell me about X', 'research Acme'). It distinguishes itself from related tools by specifying it fans out across SEC EDGAR, XBRL, USPTO, news, and GLEIF, and by contrasting with single-pack lookups and resolve_entity.

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

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

Explicit usage guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use it (when only a name is available) and directs to resolve_entity as an alternative, making the selection logic clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by explaining the rationale for deletion (stale context, task completion, sensitive data), which is useful behavioral context beyond the annotations.

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

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

The description is three sentences with no wasted words: a clear action statement, a usage condition, and a sibling pairing hint. It is front-loaded and every sentence contributes to understanding.

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

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

For a simple one-parameter tool with annotations covering destructive behavior and a fully documented schema, the description fully covers when and why to use it. No output schema exists, and the description is complete for the tool's simplicity.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to delete.' The description only repeats 'by key' without adding extra meaning, so it does not significantly enhance the schema's parameter documentation.

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

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

The description uses a specific verb ('Delete') and a clear resource ('previously stored memory by key'), which precisely states the tool's function. It also distinguishes the tool from its siblings by focusing on memory deletion rather than recall or storage.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also hints at complementary tools by saying 'Pair with remember and recall,' providing contextual direction.

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 behavioral detail beyond annotations by stating it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and that the output is 'a single text blob ready to drop at site-root/llms.txt'. This clarifies the read-only fetch/extract/emit pipeline. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower; the description adds meaningful context 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?

The description is concise and front-loaded, with three sentences covering purpose, process, and use cases. Every sentence adds value, though phrases like 'production-ready' and 'cleanly' are slightly embellished and not 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 moderate complexity, the description covers input (URL), process (fetch/extract), output (markdown text blob), and likely use cases. There is no output schema, but the return format is described. It is sufficient for an agent to select and invoke the tool correctly, though it could mention failure handling or network assumptions.

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

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

Schema description coverage is 100%, so the schema already documents both 'url' and 'max_links' fully. The description does not add parameter-specific semantics beyond mentioning 'key links' in the extraction process. Per the rubric, baseline is 3 when schema coverage is high, and the description adds minimal extra parameter value.

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

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

The description clearly states the specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It also details the process (fetts the page, extracts title/description/key links, emits standard llms.txt markdown) and mentions use cases. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, which also covers auditing AI 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: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool. It does not, however, mention when not to use it or name alternative sibling tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about the return payload (publication count, related/parent concepts), going beyond the annotations. It does not contradict annotations and gives a clear picture of expected behavior for a simple lookup.

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

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

The description is two concise sentences, front-loaded with the core action, and every clause adds information. No wasted words or redundancy with structured 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?

For a simple read-only lookup with an output schema and strong annotations, the description is nearly complete. It covers what the tool does and what it returns. A minor gap is lack of guidance on handling ambiguous or non-existent concept names, but overall it 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 100%, with 'query' and '_apiKey' already well described. The description's phrase 'by name' adds minimal value beyond the schema's 'Concept name to look up'. It does not introduce new constraints or deeper parameter semantics.

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

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

The description clearly states the tool's function: 'Look up research fields or topics by name.' It specifies the resource (concepts in the academic hierarchy) and what is returned (description, publication count, related concepts, parent concepts), which distinguishes it from sibling tools like get_scholarly_work or search_works.

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 use for concept lookup by name but provides no explicit guidance on when to prefer this tool over alternatives like search_works or entity_profile. There are no exclusions or alternative recommendations, so it is only minimally viable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: it returns the full record, reconstructed abstract, and cited works (referenced_works), which is beyond a simple fetch. It also notes that it supports ID or DOI formats, giving the agent concrete expectations.

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

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

The description is three sentences, front-loaded with the core action, then return details, then usage context. The parenthetical naming rationale is a small but useful note that prevents confusion with another tool. No redundant phrasing or filler exists.

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 states exactly what is returned (full record, abstract, referenced_works), which is sufficient for this simple fetch tool. Combined with annotations and a clear usage context, the description covers all necessary information for an agent to invoke it correctly.

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

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

Schema description coverage is 100% for both parameters (id and _apiKey), so the schema already documents the parameter meanings. The description adds example values for id (e.g., 'W2741809807' and '10.1038/s41586-021-03819-2') but these are also present in the schema's examples. Therefore, the description adds minimal extra semantic value beyond what the schema provides.

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

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

The description clearly states the tool fetches a single scholarly work from OpenAlex by OpenAlex ID or DOI, which is a specific verb+resource+method. It distinguishes itself from sibling tools like search_works by explicitly saying it fetches a single work rather than searching. The inclusion of example IDs further clarifies the exact resource.

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

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

The description explicitly says 'Use after search_works, or whenever you have a DOI/ID', giving clear when-to-use guidance. It also mentions the purpose for backward citation-graph navigation, which helps the agent decide between this and alternative lookups. While it doesn't explicitly list when-not-to-use alternatives, the guidance is clear enough for a single-record fetch 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, idempotentHint, and non-destructive behavior. The description adds value by disclosing the returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the scope to the caller's subscriptions. It also implies default filtering to active subscriptions, which is useful 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: first states purpose and returns, second gives usage guidance. No filler or redundancy. Front-loaded with the action, making it immediately scannable.

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

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

Given the simple nature (no output schema, one optional param), the description fully covers what the agent needs: what the tool does, what it returns, and when to use it. The absence of an output schema is compensated by the explicit list of returned fields.

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

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

Schema coverage is 100%: the only parameter (include_inactive) has a clear description. The tool description does not add extra parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate since the schema handles parameter explanation 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 opens with a clear verb+resource: 'List the caller's active subscriptions.' It specifies the scope (caller's) and further distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on listing. It also enumerates returned 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?

Explicitly states when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives concrete scenarios tied to sibling tools (subscribe/unsubscribe), effectively conveying when to use 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?

Despite annotations only indicating readOnlyHint=false and destructiveHint=false, the description discloses key behavioral details: filing returns a claim_token, rate limit of 5 per identifier per day, free/no quota impact, daily digest reading, and roadmap influence. It also explains the claim_token mechanism for later retrieval. 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 average but every sentence carries operational value: use cases, exclusions, token flow, rate limits, and readability. It is front-loaded with the main purpose and then progressively details usage. While not as terse as ideal, the length is justified by the need to explain cross-server exclusions and claim_token behavior.

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 4 parameters, nested context object, and no output schema, the description fully compensates by explaining return semantics (claim_token), rate limiting, free usage, and the intended audience. It also covers edge cases like 'not sure?' identification of Pipeworx tools and the instruction not to paste user prompts. The tool is completely described for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining claim_token usage in a practical call example ('pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies that it can be used standalone. It also reinforces the type enum semantics by describing the purpose of each type in context. This goes beyond the schema's structural 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 action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (Pipeworx team), the verb (tell/send feedback), and types of feedback (bug, feature, data gap, praise). This uniquely distinguishes it from all sibling tools, none of which are feedback channels.

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

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

The description explicitly states when to use the tool: when a tool returns wrong/stale data (bug), when a desired tool is missing (feature/data_gap), or when something worked well (praise). It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and instructs to file with another server for tools from different MCP servers. This is explicit when-to-use and when-not-to-use guidance with alternatives.

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

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

The description adds valuable behavioral context beyond the readOnly/idempotent annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' It explains the data source, privacy, and caching, making the tool's behavior transparent.

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

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

The description is concise, front-loaded with the core purpose, and uses a clean bullet list for use cases. Every sentence adds value without redundancy.

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

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

The tool is simple (one optional parameter, no output schema), and the description covers purpose, use cases, behavior, data source, privacy, and caching. It is fully sufficient for an agent to decide when and how to use it.

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

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

The schema description already provides full semantic detail for the single parameter: '24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.' The tool description mentions 'recent window' but does not add anything beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description immediately states what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('Returns') and resource ('top tools, top packs'), and the focus on 'trending agent calls' clearly differentiates it from sibling tools like discover_tools or search tools.

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

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

The description provides explicit use cases: 'Useful for: (1) discovering what data sources are hot... (2) confirming a popular tool is the canonical choice... (3) seeing whether your use case aligns...' It offers clear context but does not explicitly name alternatives or state when not to use it.

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

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

Annotations declare readOnly/openWorld/idempotent, and the description adds deeper behavioral context: semantic anchor Jaccard similarity threshold, partition placeholder filter, fill check against live CLOB depth, and the caveat that realizable edge can differ from theoretical edge. These go well beyond the annotation flags.

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

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

Though lengthy, each sentence earns its place. The description uses visual markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to structure complex content, and examples clarify usage. It is front-loaded with the core purpose and modes before diving into edge behaviors.

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 carries the burden of explaining return values and does so thoroughly: opportunities[], partition_check fields, skipped_low_similarity, and thin_legs[]. It covers all three modes and trade/no-trade decision criteria, making the tool fully self-contained for an agent.

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

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

Schema coverage is 100%, but the description greatly enriches both parameters: event accepts slugs or full URLs, topic expects a seed question with examples, and explains how each mode behaves (e.g., cross-event catches date-axis patterns). This adds meaning beyond the schema field descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings by naming the three modes (trending_scan, event, topic) and contrasting with related tools like polymarket_fill_risk.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also states when not to trade ('realizable_edge_pp ≤ 0 ... do not trade it') and points to an alternative tool for custom sizing.

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 extensive behavioral details: model families and formulas, slippage netting, Kelly caps, placeholder filters, the 24h-move warning, caching, and diagnostic structures. Annotations only cover read-only/idempotent safety; the description adds substantial operational context 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 very long and dense, and includes internal details like 'Run 8' and prior gate thresholds that are not necessary for tool selection. However, it is well-organized with clear sections (model families, knobs, response structure) and begins with a front-loaded purpose statement.

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

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

With no output schema, the description fully specifies the response shape: by_segment categories, fed_candidates/note, and _diagnostics with funnel counters. It explains why segments might be empty, lists all output fields (edge_pp_net, kelly_fraction, etc.), and covers caching—comprehensive for a complex tool.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds value by explaining parameter interplay—e.g., 'min_kelly never filters partition arbs' and 'slippage_pp subtracted from raw edge before ranking and Kelly sizing'—and clarifies tradeable-edge knobs, warranting a 4.

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 and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on cross-referencing Pipeworx data with market prices.

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 it is 'built for "what should I bet on today"' and explains how agents can discover opportunities without scanning hundreds of markets. It also mentions exclusions (Fed bets) and knob usage, providing implicit guidance, though it does not explicitly name alternative tools or when-not-to-use conditions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the safety profile is covered. The description adds substantial behavioral detail: the 60-day snapshot TTL, decay computed on daily closes rather than intraday, snapshot gaps on cache-misses, and the response's expired[] section explaining lifecycle. This exceeds the baseline expected from annotations.

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

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

The description is structured into purpose, args, RESPONSE, and LIMITS, with each sentence earning its place. It is longer than average but never verbose; the front-loading of the core question and the terse 'LIMITS' section keep it 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?

With no output schema, the description fully documents the return structure (tracked[], expired[], snapshot_dates[]) and their semantics, including trend classification and decay sign conventions. It also covers data availability caveats and historical depth limits. This is 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 description coverage is 100% for both parameters; the schema already explains days (default 14, clamp 2-30) and window (24hr | 1wk | 1mo). The description merely repeats the defaults and calls window a 'snapshot family', adding no new meaning. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers a concrete question ('how long has this edge existed and is it shrinking?') and explains the trading relevance, clearly distinguishing the tool's scope from sibling tools like polymarket_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?

The description implies when to use this tool by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), giving strong contextual guidance. It stops short of explicitly naming alternatives or stating when-not-to-use, so it misses the top score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: it walks the order book ladder, returns fill metrics and a verdict, and warns that partial basket fills convert an arb into an unhedged directional position. No contradiction with annotations.

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

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

The description is long and dense, packed into a single paragraph with many parentheticals and embedded mode details. It is front-loaded with the purpose, but the lack of paragraph breaks or bullets makes it harder to scan. However, every sentence carries substantive information, so it is not wasteful.

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

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

Despite having no output schema, the description enumerates all key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk) and covers edge cases and risk behavior. It is comprehensive for a tool of this complexity.

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

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

With 100% schema description coverage, the baseline is 3. The description goes further by explaining mode-specific semantics for size_usd (max spend on buys, target proceeds on sells, settlement notional in basket mode) and the automatic side selection for baskets, which adds meaning beyond the raw 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates itself from sibling polymarket tools by framing its function as a pre-trade fill-risk validation tool for arb signals.

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

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

Explicitly instructs when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' with a clear rationale about theoretical overround being uncapturable on thin books. This provides strong user guidance and distinguishes it from 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 goes far beyond the readOnly/openWorld/idempotent annotations by disclosing detailed behavioral traits: it explains the compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs 0), the meaning of temporal_alignment aligned:false, and the skipped_cross_type/subtype counters. It also explicitly cautions that pre-mapped topics may not be tradeable, exposing failure modes and edge cases that an agent would otherwise not know.

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

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

The description is long, but it is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Each technical detail supports understanding of the tool's complex behavior, though a few sentences could be tightened without losing essential information. Overall it is appropriately sized for the tool's complexity.

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

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

Given the absence of an output schema, the description fully compensates by explaining the response format (leg-by-leg prices, top_spreads_pp), the safety fields (compatibility_warning, temporal_alignment), and the meaning of the skipped_cross_type counters. It covers edge cases and limitations comprehensively, making the tool's behavior predictable to 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?

The schema already provides 100% coverage with descriptions for each parameter, but the description adds valuable context about how the parameters interact: topic auto-fetches pre-mapped macros, while explicit kalshi_event_ticker and polymarket_event_slug override the mapped side and enable custom pairings. This clarifies the relationship between parameters and their intended usage beyond the schema's examples.

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 statement of function: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." It specifies the tool's unique scope (comparing the same outcome across two venues) and elaborates with two modes (topic shortcuts and explicit pairings), distinguishing it from sibling tools that focus on single-venue analysis or arbitrage.

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

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

The description provides clear usage context by explaining the two operation modes and when each is appropriate (pre-mapped shortcuts vs custom pairings). It also includes a caveat that "Real cross-venue spreads are rarer than the macro-shortcut list suggests" and warns about compatibility issues. However, it does not explicitly name alternative tools or state when-not-to-use this tool versus siblings like polymarket_arbitrage, so it falls short of full alternative 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, so the safety profile is known. The description adds valuable context: scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)' and the behavior of omitting the key to list all saved keys. This goes beyond annotations, though it doesn't describe behavior for missing keys or return format.

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

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

Three sentences, each earning its place. The first sentence states the core function; the second gives the use case; the third explains scoping. No redundant or filler content. Information is front-loaded and easy to scan.

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

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

For a tool with one optional parameter and no output schema, the description is fully complete. It covers purpose, usage guidance, scoping, and relationship to sibling tools. The agent has everything needed to select and invoke the tool correctly.

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

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

The schema already covers the single parameter with a description, giving baseline 3. The description enhances understanding by re-stating the dual behavior ('or list all saved keys (omit the key argument)') and providing concrete examples of allowed values (target ticker, address, research notes). This adds real 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 clearly states the tool's primary action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs (retrieve/list) and specifies the resource (saved memory values), fully distinguishing it from sibling tools like remember and forget.

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 tells when to use this tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives and their relationships: 'Pair with remember to save, forget to delete.' This gives clear guidance on when to choose this tool over siblings.

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

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

The description discloses a side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which changes persistent feed state. This directly contradicts the annotations' readOnlyHint=true. The contradiction is a serious inconsistency, so the score is 1.

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

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

The description is front-loaded with the core purpose and then covers return items, filtering, mark_read, polling, and an alternate endpoint. It is about five sentences and each adds useful information, though the external URL could be considered slightly tangential. No bloat, so 4.

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

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

The description explains return contents (source, citation_uri, raw payload), filter options (type/since), the mark_read side effect, and polling suitability. It also points to a public feed URL. While it doesn't explicitly describe the exact response shape, no output schema exists, and the listed info is sufficient for practical use. Minor gaps like unread_only/limit are covered by the schema, so 4.

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

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

The input schema already covers all parameters with descriptions, so baseline is 3. The tool's description adds value by giving a concrete type example ("sec_8k"), clarifying that 'since' takes an ISO timestamp, and explaining the behavior of mark_read. These enrich the parameter semantics beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' which clearly states the tool's specific action and resource. It also distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on fired alerts and the evaluator's feed.

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

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

The description provides clear context for when to use the tool: for polling the feed, filtering by type/since, and marking events read. It also mentions an alternative URL for scripts/dashboards. However, it does not explicitly name alternatives among sibling tools or specify when not to use it, stopping short of a 5.

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

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

Even with readOnly/idempotent annotations, the description adds significant behavioral detail: parallel fan-out, source preference with fallback on rate limits/5xx, PatentsView API sunset soft-fail, and the exact return shape (changes[], total_changes, pipeworx:// URIs). 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?

Despite being dense, the description is front-loaded with recognizable query examples and every clause earns its place—sources, fallback logic, parameter syntax, output structure, and an alternative-tool pointer are all covered without fluff or repetition.

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

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

With no output schema, the description explicitly names the return fields (changes[], total_changes, citation URIs) and covers the multi-source behavior, failure modes, and date-window semantics. This is complete for an agent to decide and invoke confidently.

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

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

The schema already documents all three parameters at 100% coverage. The description adds practical value with relative shorthand examples ('7d', '30d', '3m', '1y'), a recommendation to use '30d' or '1m' for monitoring, and clarifies value accepts ticker or CIK, reinforcing and extending 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 natural-language queries and identifies the tool as a change feed for a company over a time window, with explicit fan-out to SEC EDGAR, GDELT/GNews, and USPTO. It clearly distinguishes from sibling entity_profile by noting that tool covers static profile outside a window.

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

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

It gives explicit query patterns, states the ideal use case ('what happened to Z this week/month/quarter'), and provides a direct alternative: 'Use entity_profile instead when you want the static profile...'. It also explains fallback behavior between GDELT and GNews, helping the agent choose correctly.

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

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

Adds context beyond annotations: key-value pair scoped by user identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. These details reflect real behavioral traits (auth, expiry) not captured in the annotations. 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?

Three sentences: purpose, usage guidance, and storage details. It is front-loaded with the primary action and every sentence serves a purpose without redundancy.

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

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

For a simple two-parameter memory write with annotations present, the description covers the core purpose, when to use, memory scoping, retention policy, and companion tools. No output schema exists, but a save operation's return value is trivially predictable, so no gap is material.

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

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

The schema already describes both parameters with examples (100% coverage). The description only restates 'key-value pair' without adding deeper semantics or constraints, so it meets the baseline but does not 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 opens with 'Save data the agent will need to reuse later' – a specific verb (save) and resource (data). It distinguishes from siblings by naming recall and forget as complementary tools, making its role in the memory tool family clear.

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

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

It explicitly says when to use: 'Use when you discover something worth carrying forward' with concrete examples such as a resolved ticker or user preference. It does not include when-not scenarios or direct alternatives, so it falls short of a 5.

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

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

Annotations already cover safety (readOnly, idempotent). The description adds valuable context: internal cascading lookups, graceful degradation, explicit listing of unresolved identifiers, and source labelling. 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?

Description is verbose but front-loaded with example queries. Every sentence adds value, though the internal resolution details could be more structured. Still concise relative to the amount of information conveyed.

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 and two parameters, the description thoroughly covers all relevant aspects: return identifiers, unresolved handling, graceful degradation, and even specific use cases (ISIN, ownership). It replaces the need for an output schema in terms of agent understanding.

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

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

Schema covers both parameters (100% coverage). The description enriches meaning well beyond schema: explains allowed values for 'type' with examples, details 'value' input variants for both entity types, and adds nuanced behavior like ISIN-to-LEI resolution.

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

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

The description explicitly states the tool resolves names to canonical identifiers, provides example queries, and distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID.' The verb+resource combination is specific and clear.

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

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

It gives an explicit usage guideline: 'Use FIRST whenever you have a name but need an ID.' It also details supported types (company, drug) and which identifiers are returned, implying when not to use it (when you already have an ID). Slightly more explicit 'when not to use' would push it to 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 readOnly, openWorld, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds value by disclosing that the tool calls ai_visibility_check internally, returns a ranked list, and includes score, confidence, and signal density per entity. This is meaningful context beyond annotations, though it doesn't describe error handling or rate limits.

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

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

The description is two sentences, front-loaded with the core action ('Compare AI visibility across multiple entities side-by-side'). Every sentence earns its place: the first states purpose, the second explains mechanism and return value. 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 there is no output schema, the description compensates by explicitly listing return fields (ranked list with score, confidence, signal density). Combined with strong annotations and full parameter coverage, the context is largely complete. Minor gaps: it doesn't mention model limitations or potential errors, but these are less critical for a read-only, idempotent 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 has 100% coverage with descriptions for every parameter (entities, models, _apiKey, context). The description's mention of 'your brand + N competitors' and 'shared context' merely restates what the schema already provides. With such high schema coverage, the description adds minimal new parameter-specific meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb ('Compare'), resource ('AI visibility across multiple entities'), and scope ('side-by-side'). It also specifies the mechanism ('Probes each entity with ai_visibility_check, ranks by score') and differentiates from the sibling ai_visibility_check by focusing on multi-entity comparison. The example ('does Claude know about us as well as our competitors?') further clarifies intent.

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 frames when to use: 'Useful for competitive AI-marketing audits' and provides a concrete query scenario. It implies that this tool is for comparing multiple entities, which indirectly distinguishes it from the single-entity ai_visibility_check sibling. However, it does not explicitly state 'use ai_visibility_check for a single entity' or list alternative tools, so it misses explicit exclusions.

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

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

The annotations (readOnlyHint, idempotentHint, destructiveHint: false) already signal a safe read operation. The description adds significant behavioral depth: it fans out across two services, enumerates the return summary fields, discloses partial failure behavior via sources_failed, and warns about the 5-30s latency on bundlephobia's first measurement. No contradiction with annotations.

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

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

The description is dense yet efficient: each of its five sentences adds a distinct piece of value (composite purpose, usage trigger, return fields, ecosystem scope, failure/latency behavior). No redundant phrasing, and the structure progresses logically from high-level intent to operational caveats.

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

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

With no output schema, the description compensates by fully enumerating the return fields (is_latest, license, bundle_kb_min, etc.), covering partial failure handling, and specifying the npm-only limitation. It also sets latency expectations. For a composite tool of this complexity, this is a complete and agent-ready spec.

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

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

The input schema has 100% coverage with clear descriptions for both `package` and `version`, including scoped-package syntax. The description adds no new meaning beyond the schema—it mentions using 'lodash' as an example but does not elaborate on the parameters. Baseline 3 is appropriate since the schema carries the 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 is both specific and vivid: it frames the tool as a "Composite ... check in ONE call" and explicitly enumerates the underlying services and checks (license, advisories, bundle size, etc.). It clearly distinguishes from sibling tools by scoping to npm packages and naming the exact data 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?

It explicitly states when to use the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an explicit exclusion for non-npm ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' which serves as a when-not-to-use and 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, idempotentHint, and non-destructive behavior. The description adds value by stating the exact return fields (author name, ORCID, institution, publication count, citations) and broadening the query to institution affiliation, which is not in the parameter schema. However, it doesn't mention pagination or external API quirks beyond what annotations cover.

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

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

Two sentences, front-loaded with the core action and then a list of return fields. Every sentence earns its place; no redundant phrasing.

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

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

Given the simple read-only search tool with a full input schema and output schema, the description adequately covers purpose, search criteria, and return format. The annotations cover safety and open-world aspects, making it complete for an agent to invoke.

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

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

Schema covers all parameters with descriptions (100% coverage), but the description adds crucial semantics by stating the query can be an institution affiliation, which the schema limits to 'Author name'. This extra meaning goes beyond the baseline.

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

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

The description uses a specific verb ('Find') with a clear resource ('researchers') and specifies search criteria ('by name or institution affiliation'). This distinguishes it from sibling tools like search_works and search_institutions.

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

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

The description implies the tool is for author searches but does not explicitly compare it with alternatives or state when to use it instead of a sibling. Context is clear but no exclusion or alternative is mentioned, so it relies on the agent's inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context: query can match by name or country code, and it lists return fields. No contradiction with annotations.

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

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

One concise, front-loaded sentence communicates purpose and returns, and the inline country-code example is not verbose. No unnecessary words.

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

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

For a simple search tool with full schema coverage, an output schema, and safety annotations, the description is complete. It states what to search, how (name/location), and what results look like.

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

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

Input schema covers all parameters, but the description adds meaning beyond schema by expanding query to include location/country-code search, while schema only says institution name. This is especially helpful because query is required.

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 names the specific action ('Find academic institutions') and the resource (academic institutions), with search dimensions (name or location). This distinguishes it from sibling search_authors/search_works. The country-code example further clarifies 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?

Clear context for use: when you need to find institutions by name or location. It does not explicitly mention alternatives or exclusions, but the tool's name and description make its primary use obvious.

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

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

Annotations already declare readOnly/idempotent/destructive-safe, but the description adds substantial beyond-annotation context: BGE-base-en embeddings, cosine similarity over 500-char windows, char offsets, similarity scores, and a 200K char cap with truncation flags. This reveals return format, technical behavior, and edge cases 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?

The description is three sentences, each earning its place: purpose/inputs, use case, and technical behavior. It is front-loaded with the main verb and resource, uses punctuation to signal examples and contrasts, and contains zero filler words.

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

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

Despite having no output schema, the description fully specifies the return value (passages with offsets and scores), technical method, size limits, and integration with a sibling tool. It gives an agent everything needed to decide when to call it and what to expect, making it complete for a moderately complex tool.

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

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

The input schema already covers all 3 parameters with descriptions, so the baseline is 3. The description enriches parameter meaning by framing 'text' as a fetched record, 'query' as natural-language with examples, and 'limit' as top-N passages. It also ties the 200K cap directly to the text parameter, adding interaction context beyond the schema.

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

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

The description clearly states a specific verb+resource: 'Semantic search INSIDE a fetched record' and explains the input (text already pulled) and output (top-N passages with offsets and scores). It distinguishes itself from siblings by explicitly contrasting with 'ask_pipeworx_grounded' and positioning itself as a tool for when records are too large for the prompt.

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 provided: 'Use when the record is too big to cram into the prompt.' It also names a complementary sibling tool ('Pairs with ask_pipeworx_grounded') and explains when to use the pair instead of a whole-document approach, giving clear when/when-not guidance.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds the return fields (title, authors, journal, year, citations, abstract) and broad scope, but does not disclose additional behavioral details such as result sorting or data source limitations. Given the annotation coverage, this is acceptable but not exceptional.

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

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

The description is somewhat long but well-structured: it opens with the core function, provides concrete examples, and ends with return fields. Every sentence contributes value, though a bit more conciseness could be achieved without losing the helpful examples.

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

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

With a rich output schema and 100% schema parameter coverage, the description provides enough context for an agent to select and invoke the tool. It clearly states the scope and return information. Minor omissions like result ordering or database source are not critical given the output schema exists.

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

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

The input schema has 100% coverage for all three parameters (query, limit, _apiKey). The description's example queries add useful context for what the query parameter should contain, but it does not add meaning beyond the schema for the other parameters. Baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool searches scholarly/academic research across ALL fields, using specific verbs and resources (search works/papers by title, author, or keyword). It distinguishes itself from sibling tools like search_authors and search_institutions by focusing on research works and results.

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 with example queries and explicitly lists what kinds of searches are appropriate (recent studies, papers, findings on topics). It does not explicitly mention alternatives or exclusions, but the scope is well implied through examples and the 'ALL fields' phrase.

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, the description discloses important behavioral traits: the OAuth requirement, the always-on feed behavior, SMS phone verification and 10/day cap, webhook auto-disable after 10 consecutive failures, and the one-time return of the webhook signing secret. These add substantial context without contradicting the annotations.

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

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

The description is dense and front-loaded with the core purpose, but it quickly moves into detailed type examples and delivery specifications. Every sentence adds value, though it's a long single sentence that could be easier to scan with more structure. Still, it is appropriately sized for the tool's complexity.

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

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

The description covers the return value (new subscription id), requirements (OAuth), all supported subscription types with example params, and delivery channel nuances including verification and limits. With no output schema, this is sufficient for a tool of this complexity.

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

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

The input schema already describes all three parameters with 100% coverage, including type-specific examples in the 'params' description. The description adds extra semantics such as the OAuth requirement, the 'feed (always on)' detail, and the delivery channel behaviors (e.g., phone verification, webhook auto-disable), which go 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 and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the action and output ('Returns the new subscription id'), and the listed supported types and delivery channels distinguish it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear prerequisites (OAuth account required, anonymous/BYO cannot persist subscriptions) and explains delivery channels with references to the feed ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It does not explicitly state when not to use the tool, but the context and alternatives are implied.

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 behavioral context by explaining what the tool returns (category-bucketed example questions) and how it behaves with and without the 'topic' parameter, which 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 appropriately sized for its scope, front-loaded with user-like queries to establish purpose, and every sentence contributes (what it returns, how to call, when to use). No wasted words.

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

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

For a simple tool with one optional parameter, no output schema, and rich annotations, the description covers purpose, output content, usage patterns, and timing thoroughly. It is fully complete for an onboarding tool.

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

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

Schema coverage is 100% with a clear description of the optional 'topic' parameter. The tool description repeats and slightly expands on this (e.g., 'focus', 'full spread'), but the schema already provides the essential info, 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 that just connected, specifying it returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from sibling tools like discover_tools by focusing on 'what is worth asking' rather than generic discovery.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides a clear context for use, though it does not explicitly state when not to use it or name direct alternatives beyond the meta-tools.

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

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

The description adds meaningful behavioral context beyond the annotations: it states the action is not a delete but a deactivation, explains that historical events remain available via recent_alerts, and enforces ownership. These details complement the idempotent and non-destructive hints, providing a clear picture of side effects and permissions.

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

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

The description is three sentences, each serving a distinct purpose: action, ownership constraint, and deactivation behavior. It is tightly written with no unnecessary information or repetition.

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

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

For a simple single-parameter tool with no output schema, the description is quite complete: it covers the action, the ownership constraint, and the post-effect on historical events. It does not explicitly describe error handling for invalid ids or unauthorized attempts, but given the annotations on idempotency and non-destructiveness, it is sufficient for confident invocation.

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

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

The input schema already documents the single 'id' parameter with 100% coverage, noting it is the subscription id returned by subscribe. The description merely says 'by id' without adding new parameter-specific details, so the baseline applies.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription). It distinguishes from siblings by explaining that the row is deactivated, not deleted, and that ownership is enforced, providing a precise and unambiguous 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 implies when to use the tool (to cancel a subscription) and mentions the ownership restriction, which serves as an implicit exclusion. However, it does not explicitly mention alternatives (e.g., list_subscriptions) or explicitly state when not to use it, so the guidance is only partially developed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description adds deep behavioral nuance: the two verification pathways, the exact meaning of each verdict (especially the critical distinction between could_not_verify and unsupported), and the requirement not to treat could_not_verify as evidence. This goes well beyond what annotations provide and contradicts nothing.

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

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

The description is long but well-structured: it front-loads with example queries, then the core behavior, then outcome semantics, then a caller warning, then the efficiency benefit. Every sentence carries meaningful information, though it could be tightened slightly 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?

With no output schema, the description fully compensates by enumerating all possible verdicts, confirming the return of the actual value with citation and reasoning, and detailing error semantics. It also addresses edge cases like unsupported and could_not_verify, making it self-sufficient for callers.

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 descriptions for both parameters, so baseline is 3. The description elevates this by explaining how tolerance_pct overrides the claim's implied tolerance, is capped at 5 by default, and recommending 1–2 for hallucination detection. This adds actionable guidance beyond the schema's static description.

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

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

The description opens with explicit example queries and states 'natural-language claim verification against authoritative sources', making the verb+resource+scope unmistakable. It clearly distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on fact-checking with a verdict output rather than open-ended Q&A.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies the internal decision between the SEC fast path and the grounded pipeline. It also notes that the tool replaces 4–6 sequential calls, implying when to prefer it over multi-step alternatives, but it does not explicitly name sibling tools to exclude.

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