Orcid

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 valuable context: the external call to Anthropic when _apiKey is provided, the direct payment implication, and the exact per-model return structure. This goes beyond what annotations provide.

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

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

The description is four sentences, with each sentence earning its place: main action, default behavior and cost note, return format, and use cases. It is front-loaded with the core purpose and contains no redundant or filler content.

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 without an output schema, the description adequately explains what the tool returns. It also covers the core workflow (default model, optional Anthropic) and target use cases. It lacks explicit alternatives or when-not-to-use guidance, but the overall context 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter-related context by specifying the default model (Workers AI Llama-3.3-70b), clarifying that _apiKey is only needed for Anthropic, and explaining that 'context' disambiguates entities. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about an entity and scoring visibility. It uses a specific verb ('Probe') and specifies the resource (LLMs) and outcome (0-100 score). However, it does not explicitly distinguish itself from sibling tools like scan_competitor_ai_presence, so it misses the sibling differentiation required for a 5.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and how to enable Anthropic. It does not explicitly mention exclusions or alternatives, but the context is sufficiently clear for an agent to decide when to use it.

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

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

Annotations already cover read-only/idempotent/non-destructive safety. The description adds valuable behavioral context: routing across thousands of tools, automatic argument filling, stable pipeworx:// citation URIs, works on every tier, and one-call operation. It doesn't detail potential rate limits or auth requirements, but given the annotation coverage, the added context is sufficient.

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

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

The description is lengthy but front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH'). It is organized into preference, usage, examples, and escalation sections, with no wasted sentences. The list of sources is somewhat verbose but serves to illustrate scope. Overall, well-structured despite its length.

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

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

Given the tool's simplicity (one required parameter) and lack of output schema, the description covers the essential context: what it does, when to use it, examples, and alternatives. It mentions 'structured answer with stable pipeworx:// citation URIs' as a return-value hint. Could elaborate more on the response format, but for a routing tool, this is adequate.

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

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

Schema coverage is 100% with six fully described parameters, mostly aliases for 'question'. The description complements the schema by providing multiple real-world query examples ('current US unemployment rate', 'Apple's latest 10-K') that demonstrate how to phrase the question parameter. It also notes 'fills arguments', adding context on how parameters are handled 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 clearly states the tool's function: routing questions to 5,439 tools across 1,412 verified sources and returning structured answers with citations. It explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different use cases, leaving no ambiguity about its role.

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

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

Usage guidance is explicit and extensive: 'PREFER OVER WEB SEARCH' establishes the primary context, 'START HERE for most questions' signals default use, and concrete query examples are provided. The description also gives clear escalation paths ('Step up only when needed') with named alternative tools, satisfying the when/when-not requirement perfectly.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral context beyond this: it is a full working router (not a fallback stub), routing improvements are enabled live only when a candidate is under test, and currently it matches ask_pipeworx exactly. This transparency helps the agent understand the current experimental state 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 four sentences long, each contributing essential information: identity, current status, usage guidance, and a clarification of fallback behavior. It is front-loaded with the tool's beta nature and is free of filler or redundancy. This is an ideal balance of completeness and brevity.

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

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

Despite having no output schema and the complexity of a universal router with thousands of tools, the description provides sufficient context by explicitly stating it is identical to ask_pipeworx (same tools, arguments, response shape) and referencing where to find the stable behavior. It also clarifies the current active state (no candidate) and that it is a full working router. This fully equips the agent to use the tool correctly.

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

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

The description does not mention parameters at all. However, the input schema covers 100% of the parameters, clearly explaining that 'question' is required and that query, q, prompt, text, and input are aliases. Since the schema already carries the full parameter semantics, the description adds no extra value here, warranting the baseline score of 3.

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

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

The description clearly states it is a beta version of the universal router 'ask_pipeworx' with the same 5,439 tools, arguments, and response shape. This distinguishes it from the stable ask_pipeworx and other siblings by highlighting the experimental routing aspect. The purpose is specific and unambiguous.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' giving a clear context of use. It also mentions that results are compared against the stable router, implying it is for evaluation purposes. However, it does not explicitly state when not to use it or recommend the stable alternative for production, though the 'experimental edge' phrasing carries an implicit caution.

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 substantial behavioral traits beyond the annotations: it describes the routing process, the guarantee to use only tool results, the exact success return shape, and the explicit refusal reasons (e.g., 'not_in_source', 'data_truncated'). It also mentions the extra LLM call cost, which is not in 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?

The description is dense but well-structured, with each sentence serving a purpose: defining the mode, explaining the mechanism, specifying return/refusal formats, and giving usage guidance. It is front-loaded with the key concept and includes no filler.

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

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

Despite having no output schema, the description fully explains the return value structure and all refusal reasons. It also provides context on when to use the tool and how it differs from the sibling, making it complete for a tool with a single complex parameter.

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

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

Schema description coverage is 100% with all parameters documented as aliases for the main 'question' parameter. The description does not add any extra parameter semantics, but the schema already fully explains them, so the baseline score of 3 applies.

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

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

The description clearly states it's a 'hallucination-resistant answer mode for high-stakes reads' with a specific extraction mechanism ('EXTRACTS the answer using ONLY what the tool result contains'). It explicitly distinguishes itself from the sibling 'ask_pipeworx' by noting 'Same routing' but adding grounded extraction and refusal modes.

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

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

Explicit usage guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost tradeoff of 'one extra LLM call.'

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

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

Despite annotations already covering read-only, idempotent, and non-destructive behavior, the description adds extensive behavioral context: resolver contract (market_match_confidence), blocking statuses ('low_confidence_match', 'market_closed_or_inactive'), wide-spread illiquidity warnings, cancellation-rule parsing, and fallback mechanics for news sources. This goes far beyond the annotations and is highly valuable for an agent.

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

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

The description is long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose in the first sentence. While it could arguably be trimmed, the length is justified by the tool's complexity and the absence of an output schema. The format aids scannability.

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

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

With no output schema, the description fully specifies the response structure: result.market, result.analysis, result.evidence, parent_event, news fallback fields, and status codes. It also covers edge cases like closed/dead markets, wide spreads, and low-confidence matches. This is a complete behavioral contract for the agent, leaving little to guess.

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 all three parameters with clear descriptions. The tool description repeats the input formats for 'market' and mentions defaults for 'depth' and 'include_raw', but adds no new parameter-level semantics beyond what the schema defines. Therefore, the baseline of 3 is appropriate since the schema carries the load.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_edges or validate_claim by focusing on bespoke data assembly for individual bets. The intended use cases are explicitly listed ('should I bet on X', 'what does the data say about Y'), making the purpose unambiguous.

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

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

The description provides clear when-to-use guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly mention when not to use this tool or name alternative tools (e.g., polymarket_arbitrage for spread analysis). Thus it has clear context but no exclusions.

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

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

Discloses that it pulls latest 10-K data for companies and FAERS trial data for drugs, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. Adds substantial 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 front-loaded with example queries and core statement, then expands into data details. Though somewhat long, each sentence provides essential information with no unnecessary 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 mentions return format (paired data + citation URIs) and covers data sources, sorting, and usage. Minor gaps around error handling are acceptable given 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%, so parameters are documented. The description adds meaning by specifying what data each type ('company' vs 'drug') retrieves, exceeding the schema's basic descriptions.

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

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

Clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. Uses specific verbs like 'compare' and provides example query patterns. Differentiates from sequential single-entity lookups.

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

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

Explicitly says to prefer this over sequential single-entity lookups when comparing entities. Provides clear context for when to use (comparing multiple entities) and what data each type pulls. Implicitly tells users not to use for single-entity lookups.

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

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

Beyond the readOnly/idempotent annotations, the description discloses critical behaviors: account requirements and paid plan for 'thorough', the exact return packet structure ('verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation'), gap handling ('never invented', 'explicit gaps[]'), depth-specific iteration logic, contradiction detection, semantic excerpting rather than truncation, and latency expectations (15-60s, up to ~90s). This is rich behavioral context that goes far beyond annotations.

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

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

The description is long (~400 words) but densely informative. It front-loads critical account/alternative info and then systematically covers mechanism, use cases, depth tiers, output format, limitations, and performance. While there is some repetition of 'gaps[]' and 'ask_pipeworx', every sentence contributes meaningful context; it could be trimmed slightly but remains appropriately structured for a complex multi-tool research service.

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

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

Despite lacking an output schema, the description fully specifies the return format (findings packet, gaps[], contradictions[], hop, citation_uri, excerpted passages), covers auth prerequisites, alternative tools, depth semantics, news-domain limitations, and latency. It leaves no major operational unknown, making it complete for an agent to invoke and interpret results.

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

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

Schema description coverage is 100% and the schema already thoroughly documents both parameters (question and depth enum with detailed tier explanations). The description adds practical semantics like 'Broad/multi-part is fine — decomposition is the point' for the question parameter and clarifies real-world outcomes of depth choices (e.g., 'so multi-step questions resolve in one call', time estimates). This exceeds the baseline of 3, though the schema already does heavy lifting.

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

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

The description clearly states the tool's specific action: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' that 'Decomposes your question into focused facets, routes each to the right one of 5,439 tools IN PARALLEL, and returns a findings packet.' It explicitly distinguishes from open-web search and from sibling tools like ask_pipeworx, making the purpose unambiguous and differentiated.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead.' It also offers tier-based recommendations (quick/standard/thorough) with consequences, which fully satisfies the when/when-not/alternatives requirement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas, and promises that results are 'ready to call directly, no second schema lookup needed'. This goes beyond the annotations, though it does not detail ranking or any output format nuances.

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 ('Find tools by describing the data or task'), then quickly moves to usage context, domain examples, and return behavior. Every sentence contributes meaningful information, and the structure is tight without unnecessary fluff.

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

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

Given the tool's meta-purpose, the description fully covers what it does, when to use it, what it returns, and why it's efficient (no second schema lookup). The absence of an output schema is compensated by the description explaining the return payload. The schema covers parameters. This is complete for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage with descriptions for all parameters, including query and its aliases, and limit. The description reinforces that query is a natural language description of a task or data, but does not add new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with 'Find tools by describing the data or task', which clearly states a specific verb (find) and resource (tools). It further distinguishes itself from siblings by positioning it as a discovery tool that returns the top-N relevant tools, and explicitly says to 'Call this FIRST when you have many tools available and want to see the option set'. This is specific and differentiates it from direct-answer 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 guidance on when to use the tool ('Use when you need to browse, search, look up, or discover what tools exist'), enumerates specific domains, and directs the agent to 'Call this FIRST' when exploring the option set. This gives clear context for use and implicitly contrasts with tools that provide a single answer.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description 'Education summary' adds no behavioral context, such as what data is included, how it is filtered, or any limitations. It neither contradicts the annotations nor enriches 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 extremely brief (two words) but fails to convey the essential purpose. It is under-specified rather than concise; every word is generic and doesn't earn its place.

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

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

With one parameter and an output schema, the tool is simple, but the description is too sparse to understand the expected behavior or results. There is no indication of what an 'Education summary' contains or how it relates to an ORCID record.

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 defines a single required 'orcid_id' string with no description, and the schema description coverage is 0%. The tool description does not explain what 'orcid_id' is or how it is used, leaving the parameter semantics entirely to the name.

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 'Education summary' is a noun phrase that restates the tool name without an action verb. It does not explicitly state what the tool does (e.g., retrieve or summarize education data) nor does it distinguish it from sibling tools like 'employment' or '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?

No guidance is provided for when to use this tool. There are no mentions of alternatives, prerequisites, or exclusions. Sibling tools such as 'employment', 'works', and 'entity_profile' overlap in potential purpose, but the description offers no differentiator.

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, which conveys safety. However, the description adds no behavioral context beyond what annotations provide—no mention of what data is returned, whether it summarizes multiple entries, or any limitations. Thus, the description contributes nothing beyond the structured metadata.

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

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

The description is two words long, which is extremely concise, but it is under-specified to the point of being unhelpful. There is no structure or substantive content; it does not convey any information beyond the tool name, so the conciseness is not a virtue but a deficiency.

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 a simple interface (one required parameter) and strong annotations, the description is too vague to be complete. It does not state the tool's purpose, how the parameter works, or what the output represents. An agent cannot confidently select or call this tool based on the provided description alone.

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

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

Schema description coverage is 0%, meaning the 'orcid_id' parameter has no description in the schema. The description 'Employment summary' does not mention the parameter or explain what orcid_id represents or how it is used. This leaves the agent entirely without semantic guidance for populating the parameter, making the tool unusable without external knowledge.

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 'Employment summary' is essentially a restatement of the tool name, adding only the noun 'summary' without specifying an action, resource, or scope. It does not clarify what function it performs (e.g., 'Retrieve employment history for an ORCID record') and fails to distinguish it from sibling tools like 'work' or 'education'.

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?

There is no guidance on when to use this tool, what scenarios it applies to, or how it differs from alternatives such as 'work' or 'works'. The description gives no context for selection, leaving the agent to infer usage from the tool name and parameter.

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 details multi-source fan-out, return structure (cik, filings with URIs, fundamentals, patents, news, LEI), and caveats like 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated' and 'GDELT→GNews fallback'. No contradiction with annotations.

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

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

The description is long but information-dense and well-structured. Example queries are front-loaded for quick pattern recognition, and the semicolon-separated details are easy to parse. A few redundant examples could be trimmed, but every sentence earns its place.

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

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

With no output schema, the description carries the full burden of explaining return values. It enumerates all components (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and includes caveats, making it sufficient for reliable invocation of this complex multi-source tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds concrete examples ('AAPL', '0000320193') and reinforces the zero-padded CIK format. It also clarifies that only 'company' is supported for type, adding practical 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 'full cross-source profile of a US public company in ONE parallel call' and lists multiple example queries. It explicitly contrasts with chaining single-pack lookups and references resolve_entity for name-only cases, distinguishing it from siblings.

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

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

It gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states exclusions ('names not supported') and directs to resolve_entity as an alternative, making usage boundaries crystal clear.

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

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

The description discloses the destructive nature ('Delete') and adds context about clearing 'sensitive data,' which enriches the behavioral profile beyond the annotations (destructiveHint=true, idempotentHint=true). It does not mention side effects like irreversibility, but the annotations already cover the core safety aspects.

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

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

Three short sentences: the first states the action, the second provides usage conditions, and the third names related tools. Every sentence adds value, no filler or repetition.

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

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

For a simple single-parameter delete operation with strong annotations and an explicit description, this is largely complete. It covers the action, the trigger, and related tools. The lack of an output schema is compensated by the straightforward nature of the operation, though it never states what happens after deletion (e.g., success confirmation).

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 'Memory key to delete' fully explaining the purpose of 'key.' The description reinforces this with 'by key' and 'previously stored memory' without adding significant new meaning. Baseline 3 is appropriate given the high schema coverage.

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

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

The description opens with 'Delete a previously stored memory by key,' which is a specific verb+resource combination that clearly distinguishes this from sibling tools like 'remember' and 'recall.' It also implies the scope of operation (existing memory) and the parameter (key).

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: 'when context is stale, the task is done, or you want to clear sensitive data.' Also provides guidance on complementary tools: 'Pair with remember and recall.' This meets the 'when/when-not/alternatives' criterion, even though it doesn't mention a when-not.

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 tool's safety profile is known. The description adds valuable behavioral context: it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and states the output is 'a single text blob ready to drop at site-root/llms.txt.' This explains the process and output without repeating 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 concise and well-structured. It front-loads the primary purpose, then provides a brief process explanation, and ends with specific use cases. Every sentence adds value without redundancy, and the length is appropriate 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?

For a simple tool with two parameters and no output schema, the description is complete. It explains what the tool does, how it works, the output format ('standard llms.txt markdown format'), and practical use cases. Given the annotations cover safety and the schema covers parameters, there are no significant gaps.

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

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

The schema documentation covers both parameters (url and max_links) with descriptions, achieving 100% coverage. The description adds no additional parameter semantics beyond reinforcing that the tool works for 'any URL,' which the schema already implies. Since the schema carries the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL' and details the process (fetches, extracts, emits). It is highly specific about the resource (llms.txt) and verb (generate). However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it falls short of a 5.

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

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

The description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It gives context on when to use the tool but does not mention when not to use it or name specific alternative tools, so it lacks explicit exclusions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds value by specifying that it returns active subscriptions by default, the specific output fields, and that 'include_inactive' can change behavior. This goes beyond the structured 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?

Two sentences, zero filler. The first sentence states the action and return fields; the second provides usage context. Every word earns its place, making it highly scannable and efficient.

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

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

The tool is simple with one optional parameter and no output schema. The description covers return fields, default behavior, and usage scenarios. It lacks mention of pagination or limits, but for a list tool this is not a significant gap given the context. The description is sufficiently complete.

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

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

Schema coverage is 100%, and the parameter 'include_inactive' is fully described in the schema. The description's mention of 'active subscriptions' aligns with the default false, but it does not add new semantic detail beyond the schema. Baseline 3 applies because the schema handles the 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 ('List') and resource ('caller's active subscriptions'), and clearly distinguishes from siblings by focusing on reading vs. creating/canceling (subscribe/unsubscribe). It also lists exact return fields, leaving no ambiguity about what the tool does.

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

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

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 and implies alternatives (subscribe/unsubscribe). It provides clear practical guidance for an agent.

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

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

Annotations only indicate readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, so the description carries most of the behavioral load. It adds valuable context: rate-limited to 5 per identifier per day, free and not counting against tool-call quota, and that the team reads digests daily with direct roadmap impact. This is substantive beyond the annotations, though it does not mention auth or a return value, which would round it out.

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 one-sentence purpose, followed by clear usage cases, exclusions, and constraints. It is somewhat dense but every sentence serves a purpose—no filler or redundancy. The only minor deduction is that it could be trimmed slightly by merging the 'Not sure?' sentence with the earlier 'ONLY for tools served by this Pipeworx connection' point.

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

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

For a feedback tool with no output schema, the description covers the essential context: what to report, when to report, when not to report, rate limits, quota accounting, and expected impact. It does not explicitly state what happens after submission (e.g., confirmation or receipt), but the digest/roadmap note implies the outcome sufficiently. Overall it is complete enough for an agent to invoke correctly.

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

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

The schema already documents all three parameters at 100% coverage, including enum meanings and the nested context object. The description adds practical parameter guidance: describe the issue in terms of Pipeworx tools/packs, don't paste the end-user prompt, and be specific in the message. This supplements the schema by advising how to fill the fields effectively rather than merely repeating their definitions.

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

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

The description opens with a clear action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately distinguishes this from sibling tools by specifying it is for feedback about Pipeworx tools. It names the exact types of feedback (bug, feature/data_gap, praise) and ties them to concrete tool behaviors. This leaves no ambiguity about what the tool does or how it differs from search/ask tools.

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

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

The description gives explicit 'Use when' scenarios: when a tool returns wrong/stale data (bug), when a tool is missing (feature/data_gap), or when something worked well (praise). It also provides a clear exclusion: do not use for tools from other MCP servers, and instructs the agent to file those elsewhere. The added guidance about not pasting end-user prompts and checking Pipeworx tool names further clarifies correct usage.

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 the data is a 'self-aggregating signal' from an analytics engine, contains 'no PII', and is 'cached 5min-1h depending on window.' This adds meaningful context about data provenance, privacy, and freshness that the annotations do not cover.

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

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

The description is well-structured: a clear lead sentence, a numbered 'Useful for' list, and a final technical note. Every sentence adds distinct value, and the length is appropriate for the amount of context provided—it is informative without being bloated.

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 one optional parameter, no output schema, and strong annotations, the description covers the tool's return values, data source, use cases, and caching behavior. This is sufficient for an agent to select and invoke the tool correctly without ambiguity.

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

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

The schema already fully describes the single `window` parameter, including its enum values, default, and the tradeoff between shorter and longer windows. The description merely repeats the window options in parentheses without adding new parameter-level semantics, so it lands at the baseline for a schema with 100% description coverage.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' and frames it as 'What other AI agents are calling on Pipeworx right now,' which is a specific verb+resource+scope. It distinguishes itself from siblings like discover_tools by focusing on trending/call-volume data rather than general tool 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?

The description provides three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It also gives guidance on choosing the window parameter (shorter for 'hot right now', longer for 'steady-state demand'). However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of the 'explicit exclusions' bar.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds deep behavioral context: Jaccard similarity threshold, placeholder-slug filtering, partition_check logic, fill check against live CLOB depth, and the meaning of skipped_low_similarity. 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 front-loads the core purpose, then uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and remains dense without fluff. Though long, every sentence earns its place given the tool's complexity, and examples make it highly readable.

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

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

There is no output schema, but the description explicitly lists response fields (opportunities[], partition_check{...}) and explains edge cases like null arb signal for placeholder-heavy partitions and the meaning of fill_check results. It covers all modes, alternatives, and safety warnings, making it self-contained.

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

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

Schema descriptions for 'event' and 'topic' are already present (100% coverage), but the description adds substantial meaning: what 'event' slugs look like, that 'event' walks child markets and checks date/threshold ordering, and that 'topic' searches related events and compares the union, catching cross-event patterns.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings by mentioning 'For custom sizing use polymarket_fill_risk' and by detailing unique modes (trending_scan, event, topic).

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 instructions are given: 'Call with NO args for a trending_scan...', 'pass event for...', 'or topic for...'. It also names an alternative tool for custom sizing (polymarket_fill_risk) and provides a do-not-trade condition when fill check results in realizable_edge_pp ≤ 0.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: model-family logic, edge computation after slippage, 24h-move warnings, 'rare-by-design' longshots, caching at the KV level keyed on all knobs, and diagnostics to explain empty segments. It even explains why Fed bets are unreliable. 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 long but well-organized: a one-sentence summary, then model families, knobs, response top-level, and diagnostics. All sections earn their place given the tool's complexity (9 parameters, no output schema). It is front-loaded with the core purpose. However, it is densely packed and could be split into shorter paragraphs for easier scanning.

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

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

With no output schema, the description fully explains the return structure: by_segment groups, fed_candidates/fed_note, and _diagnostics with funnel counters. It also covers edge calculations, slippage assumptions, and the rationale behind each model family. For a tool this complex, the description leaves little ambiguity about what the agent will receive or why a segment might be empty.

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 rich descriptions for all 9 parameters. The description adds extra semantic context for the 'TRADEABLE-EDGE KNOBS' (min_liquidity, max_spread_pp, min_partition_leg_kelly) and clarifies how min_kelly is overridden by per-leg Kelly in partitions. This goes beyond the schema, justifying a 4 rather than a baseline 3.

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

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

The description opens with a specific verb+resource+goal: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly positions the tool for discovering betting opportunities without paging through many markets, and the detailed segment breakdown (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description states a clear use case ('Built for "what should I bet on today"') and gives context like the Fed note explaining why those candidates are surfaced but not ranked. However, it does not explicitly contrast with alternatives such as polymarket_arbitrage or polymarket_edge_tracker, so it stops short of full when-versus-sibling 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?

Despite readOnly/annotations already being safe, the description adds substantial behavioral context: snapshots are written on cache-miss (gaps mean no scan), history is bounded by a 60-day TTL, and decay numbers are computed from daily closes of edge_pp_net (not intraday). It also details the response semantics (trend classification, signed edge value, expired opportunities with lifespan), going far 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?

Although the description is long, it follows a clear structure: purpose, the core question, argument details, response format, and limitations. Every sentence adds critical information—no filler. It front-loads the purpose and then logically progresses through inputs, outputs, and edge cases, making it 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: tracked[] includes full time-series, first_seen, trend, and decay; expired[] includes lifespan_days; snapshot_dates[] explains data gaps. It also addresses historical limits (60-day TTL) and computational caveats (daily closes vs intraday), making it self-sufficient for an agent to correctly interpret results.

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

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

The schema already covers both params (100% coverage), so the baseline is 3. The description enhances this by explaining the meaning of 'window' as a snapshot family and 'days' as lookback, and it reinforces defaults and max (14/30, default 1wk). This adds context beyond the schema's descriptions, which only state types and defaults.

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 'Edge persistence and decay telemetry' and directly answers 'how long has this edge existed and is it shrinking?', making the tool's core function unmistakable. It actively distinguishes itself from a simple edge snapshot tool by contrasting a 'fresh wide edge' with a '3-week-old wide edge', which differentiates it from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

The description implies when to use this tool: when you need historical edge persistence/decay rather than just current edge values. It gives clear context with the question 'how long has this edge existed and is it shrinking?' and describes the inputs (days, window) and output structure. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral detail: it walks the order-book ladder, returns fill metrics, and warns about partial basket fills converting an arb into an unhedged directional position. This is 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 long, the description is dense with essential information and uses uppercase labels to organize modes. It could be more structured with bullet points, but every sentence contributes to understanding the tool.

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

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

With no output schema, the description compensates by listing return fields such as top_of_book, vwap_fill_price, capture_ratio, thin_legs[], and forced_directional_risk. It also explains both modes and edge cases, making it adequate for an agent to invoke correctly.

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

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

Schema covers 100% of parameters with descriptions. Description adds interpretation: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode, plus default and clamp values. This enriches 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 states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with a specific verb and resource. It clearly distinguishes from siblings by naming polymarket_arbitrage and polymarket_edges as related 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?

Explicitly directs usage: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the rationale: theoretical overround on thin books is not capturable and partial fills create directional risk.

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

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

The description goes well beyond the annotations by disclosing exact behavior: it explains what triggers compatibility_warning (two distinct cases), what temporal_alignment indicates, and what skipped_cross_type/subtype counters mean. It also honestly states that real cross-venue spreads are rarer than the shortcut list suggests, preventing over-reliance. No contradiction with annotations; in fact, the read-only, idempotent hints are consistent with the descriptive content.

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 serves a purpose, covering core purpose, modes, response format, and safety fields. It is front-loaded with the central function and progressively elaborates. However, the heavy use of parentheticals and stream-of-consciousness style somewhat hurts readability; a more structured layout (e.g., bullet points) would improve conciseness while retaining the dense information.

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

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

Given no output schema, the description thoroughly explains all response components: matched pairs, spread values, compatibility warnings, temporal alignment, and skip counters. It addresses edge cases like mismatched bet shapes and temporal mismatches, making the tool's behavior fully anticipated for an agent. No significant gaps remain.

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

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

Schema coverage is 100%, but the description adds critical semantics: it lists the exact allowed values for `topic`, explains how explicit params override the mapped ones, and provides concrete example formats for each param (e.g., 'KXFED-26OCT', 'fed-decision-in-june-825'). This enriches the schema's basic descriptions with real usage context.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, explicitly distinguishing it from other tools. It details two operating modes (topic shortcuts and explicit tickers/slugs) and describes the response structure (spread[], compatibility_warning, temporal_alignment). This is a specific verb+resource with clear scope, differentiating it from siblings like polymarket_arbitrage and 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 explains when to use `topic` vs explicit parameters, noting that explicit params override the topic-mapped side. It also provides strong usage caveats: it warns that most pre-mapped topics return compatibility_warning and that 'pre-mapped ≠ tradeable', helping users avoid false signals. It does not explicitly name alternative tools, but the mode guidance and warning about meaningful vs meaningless spreads effectively steers usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful context beyond annotations with 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID),' explaining isolation and scope, plus the listing behavior when the key is omitted.

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 long, front-loads the core purpose, and every sentence earns its place by adding either purpose, usage context, or scope. No redundancies or fluff.

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

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

For a simple tool with one optional parameter and comprehensive annotations, the description covers the essential behaviors: retrieval, listing, scope, and pairing with siblings. The absence of an output schema is acceptable given the low complexity, though return format details are not specified.

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

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

Schema coverage is 100% and the schema property description already explains the 'key' behavior ('omit to list all keys'). The tool description reiterates this but adds no new parameter-specific semantics, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly distinguishes the tool from siblings like 'remember' and 'forget' by naming the complementary operations.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names paired tools: 'Pair with remember to save, forget to delete,' providing clear 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?

The description explicitly describes a mutating operation via 'Set mark_read:true to flag returned events read so the next call only shows newer ones', which contradicts the annotations readOnlyHint:true and idempotentHint:true. This is a significant annotation contradiction, and per rubric the score must be 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 three sentences, front-loaded with the core verb and resource, and every sentence adds essential information: return contents, filtering/mark_read behavior, and polling/alternate endpoint. There is no filler or redundancy.

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

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

The description is thorough for a feed-retrieval tool: it covers return fields, filtering, stateful mark_read, and an alternative HTTP endpoint. With no output schema, it sufficiently describes the return payload. It could mention pagination or default limit behavior, but the limit parameter is already in the schema, so a 4 is appropriate.

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%, giving a baseline of 3. The description adds value beyond the schema by providing a concrete type example ('sec_8k'), clarifying the since format as ISO timestamp, and explaining the consequence of mark_read on subsequent calls—making the behavior more understandable.

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 is a specific verb+resource pair. It distinguishes itself from sibling tools like list_subscriptions and recent_changes by explicitly mentioning the evaluator-written alerts, persisted feed, and the return fields (source, citation_uri, raw payload).

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 statement 'Polls work fine' gives clear usage context, and pointing to the same feed at GET registry.pipeworx.io/alerts.json offers an alternative for scripts/dashboards. However, it does not explicitly name when to use this tool over sibling MCP tools, though the context is clear.

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

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

Despite annotations already declaring readOnly/idempotent/non-destructive, the description adds substantial operational detail: parallel fan-out to SEC EDGAR, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to PatentsView API sunset, and the structure of returned changes[] with citation 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?

Well-structured with front-loaded examples and dense information, but the `since` format explanation duplicates the schema's parameter description, adding minor redundancy in an otherwise efficient description.

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

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

For a complex tool with no output schema, the description covers sources, fallbacks, return summary, time-window semantics, and the relevant alternative. The only missing details are individual change object fields, but the grouped changes[] description is sufficient for agent invocation.

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

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

Schema description coverage is 100%, and all three parameters are clearly documented in the schema. The description repeats `since` formats and value semantics without adding new parameter-level information, so baseline 3 applies.

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

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

Description clearly identifies a 'change feed for a company in the last N days/weeks/months' with multiple source types, and explicitly distinguishes from sibling entity_profile by contrasting dynamic change feed vs static profile.

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

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

Opens with natural-language query examples that signal intent, and explicitly instructs 'Use entity_profile instead when you want the static profile...' It also explains source fallback behavior, making when-to-use conditions 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 the tool as read-only, idempotent, and non-destructive. The description adds that the record is 'full' and 'public', clarifying the scope of data returned, but does not detail additional behaviors like pagination 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 a single, lean sentence that directly conveys the purpose and gives an example. No superfluous 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 single-parameter retrieval tool with an output schema, the description is sufficient. It explains the input and purpose, and the output is presumed covered by the schema. It could mention error cases or the requirement for the record to be public, but that is implicit.

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 leaves the 'orcid_id' parameter undocumented, but the description explicitly identifies it as an ORCID iD and provides an example format, compensating for the missing schema documentation.

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

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

The description clearly states the tool retrieves a full public record for a given ORCID iD, using a specific verb and resource. It distinguishes from sibling tools like 'works' or 'employment' by indicating it covers the full record.

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 implicitly signals usage for retrieving complete ORCID records and gives an example, but it does not explicitly compare with sibling tools such as 'works' or 'education' or state when to prefer this over them.

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

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

Beyond annotations, the description reveals key behavioral details: storage is key-value scoped by agent identifier, persistence differs for authenticated (persistent) vs anonymous (24 hours), and it pairs with recall/forget. This adds meaningful context that annotations alone do not provide.

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

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

The description is three sentences, front-loaded with the core purpose, then examples, storage mechanics, and companion tools. Every sentence serves a distinct purpose with no redundancy or filler.

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

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

For a simple two-parameter key-value tool with rich schema descriptions and annotations covering idempotence and non-destructiveness, the description fully covers when to use it, how data is scoped, persistence behavior, and related operations. No output schema is needed for this write-only tool.

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

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

Schema coverage is 100%, so base score is 3. The description adds value by clarifying that the key is scoped by the agent's identifier, reducing concerns about key collisions, and by giving real-world examples of value content. It does not deeply expand on parameter syntax, but the schema already covers that.

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

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

The description clearly states the tool saves data for future reuse across conversations/sessions, using the specific verb 'Save' and resource 'data.' It distinguishes itself from sibling tools like recall and forget by explicitly naming them as companion operations.

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

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

The description provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and explains the benefit ('so you don't have to look it up again'). It names recall and forget as paired tools, but does not explicitly state when not to use it or provide alternative tool comparisons.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive; the description adds return format details (ticker, CIK, company_name, citation URI; RxCUI, ingredient, brand) and notes internal cascading through endpoints. It also discloses auto-disambiguation for company input. This is valuable 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 efficiently organized: intent examples, purpose, supported types, and output details. No wasted sentences; every clause adds information.

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

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

With no output schema, the description fully covers return values for both entity types, input flexibility, citation URIs, and internal behavior. It is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with both parameters well-described, so the baseline is 3. The description reinforces the value formats but does not add new 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 resolves user-spoken names to canonical identifiers, with concrete examples ('What's the ticker for…') and supported types (company, drug). It distinguishes from siblings by positioning itself as the first step for name-to-ID lookup.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It does not specify when not to use it or name alternative tools, but the context makes the primary use case unambiguous.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable process details: it 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and returns a 'ranked list with score, confidence, signal density per entity.' This discloses the underlying mechanism and output structure well beyond the schema.

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

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

The description is three sentences with no filler. It front-loads the primary purpose in sentence one, explains the mechanism in sentence two, and gives a motivating example in sentence three. Every sentence earns its place and the structure is optimal.

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 moderate-complexity read-only tool with a comprehensive schema and no output schema, the description explicitly states the return format ('ranked list with score, confidence, signal density per entity') and the underlying probe. It does not mention potential latency or cost of multiple AI probes, but that is not essential for correct invocation. Overall, it provides sufficient context for an agent to select and use the tool effectively.

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

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

The input schema provides 100% coverage with descriptive comments for all four parameters, including entities, models, _apiKey, and context. The description adds the competitive framing ('your brand + N competitors') but this is also present in the schema's entities description. Since the schema already carries the parameter semantics, the description adds minimal extra value.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from siblings by mentioning it probes with ai_visibility_check and targets competitive AI-marketing audits, making it distinct from single-entity or generic comparison tools.

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

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

It provides a concrete use case: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' This clarifies when to use the tool. It also references ai_visibility_check, implying the alternative for single-entity checks, though it does not explicitly exclude other comparison tools like compare_entities.

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

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

Exceeds annotation coverage by disclosing partial failure behavior (bundlephobia first measurement can take 5-30s, sources_failed will list timeouts), NPM-only limitation, and the exact return block structure. No contradictions with readOnlyHint.

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

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

Description is dense but every sentence carries value: purpose, usage, return fields, ecosystem scope, failure handling. Slightly longer than strictly necessary, but well-front-loaded with the main purpose in the first sentence.

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 explains return values (summary block, advisory details, links, recent versions) and edge cases (timeouts, sources_failed). It covers scope limitations and degradation behavior, making it complete for a composite read-only 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 descriptions for both fields (package accepts scoped packages, version defaults to latest). The description adds no new parameter-specific meaning, so baseline 3 applies.

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

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

The description clearly states the tool is a composite check for 'should I add this npm package to my project', specifying it fans out across deps.dev and bundlephobia. It distinguishes from siblings by explicitly limiting to NPM and pointing to deps.dev:version for other ecosystems.

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

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

Provides explicit usage triggers ('Use whenever an agent asks "is X safe / popular / small"') and an alternative for non-NPM packages (PyPI/Maven/Cargo/Go fall under deps.dev:version). This satisfies both when and when-not/alternatives.

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

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

Annotations already disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by specifying 'Solr-style query' syntax, which is not present in the annotations and informs how the query parameter should be structured.

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

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

The description is a single, concise sentence that immediately conveys the tool's purpose and key differentiator. No unnecessary words or repetition.

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

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

Given the presence of a full output schema, 100% parameter coverage, and strong annotations, the description is appropriately scoped. It could mention pagination behavior, but the schema already defines 'start' and 'rows', so this is not a critical omission. The Solr-style query hint is sufficient contextual detail.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by labeling the query as 'Solr-style', which clarifies the query syntax format beyond the schema examples. This gives agents additional guidance on constructing valid queries.

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 ('search') and resource ('ORCID Registry'), and the phrase 'Expanded search (Solr-style query)' clearly indicates a broader search capability with a particular query syntax. This distinguishes it from sibling tools like 'search_within'.

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

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

The description implies this tool is for expanded searches across the entire ORCID Registry, which gives some usage context. However, it does not explicitly explain when to use this tool over alternatives like 'search_within' or 'compare_entities'. No alternative tools are named.

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

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

The description goes far beyond the annotations, disclosing return format (passages with character offsets and similarity scores), truncation behavior (200K char cap, flagged), and implementation details (BGE-base-en embeddings, cosine similarity, 500-char overlapping windows). This adds valuable context not present in 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 four sentences with no fluff. It leads with the core purpose, then provides usage context, pairing guidance, and technical limits. Every sentence contributes meaningful information, and the structure is 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?

Despite having no output schema, the description explains the return value (passages with offsets and scores), covers the 200K character limit and flagging, and describes the algorithm. Combined with the excellent annotations and parameter schemas, the description is complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description augments this with concrete examples for the query parameter and clarifies that 'text' is the already-fetched record, providing richer semantic context than the schema alone. However, the schema already describes each parameter adequately, so the added value is modest but present.

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

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

The description clearly states the tool performs semantic search inside a supplied text, using the verb 'search' plus the resource 'a fetched record.' It distinguishes itself from sibling tools by explicitly contrasting with ask_pipeworx_grounded and framing the use case as searching within already-pulled content rather than broad search.

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

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

The description gives explicit guidance on when to use it: when the record is too big to fit in the prompt, and it names an alternative pattern (pairing with ask_pipeworx_grounded). It does not explicitly state when not to use it, but the 'use when' condition is clear enough to guide selection.

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

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

Annotations provide basic flags (readOnly=false, idempotent=true), and the description adds critical behavior: OAuth requirement, phone verification, 10/day SMS cap, webhook one-time secret, auto-disabling after 10 failures, and return of subscription id.

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

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

The description is long but structured with clear types and delivery options. It front-loads the purpose and uses colons and examples effectively, though some content duplicates the 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?

For a complex tool with nested objects and no output schema, it covers prerequisites, types, delivery channels, and expectable side effects (SMS cap, webhook behavior). It's sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% and highly detailed, including delivery specs, so the description mainly restates what's in the schema. It adds minor semantic nuance (e.g., interpreting items codes) but no essential additional meaning.

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 object: 'Create a proactive monitoring subscription to a live-data event stream.' It also lists supported types and delivery channels, distinguishing 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?

It specifies prerequisites (OAuth account, verified phone for SMS) and describes when to use the feed vs pull via recent_alerts, but doesn't explicitly exclude alternatives like one-time search 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 mark it as read-only, open-world, idempotent, and non-destructive. The description adds context that it pulls from the 'live catalog of thousands of tools' and returns executable examples, which is consistent with annotations. It does not disclose any additional side effects, but the annotation coverage lowers the burden and the added context is useful.

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 user-style queries to aid natural language matching, then explains the return structure and invocation pattern. While it is somewhat verbose with multiple synonyms, each sentence serves a functional purpose and the structure flows logically.

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 a single optional parameter and no output schema, the description fully covers what it returns, how to call it, and when to use it. It also names related meta-tools, providing sufficient context for an agent to decide if it is the right tool.

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

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

The schema already covers `topic` with a full enumeration, so the baseline is 3. The description adds value by providing concrete examples ('finance', 'pharma', 'betting') and explaining that omitting it yields a cross-category spread. This enriches the parameter understanding 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 explicitly states it is the 'onboarding entry point' that returns 'category-bucketed example questions... each with the exact tool + argument shape that answers it.' This gives a specific verb (suggest questions) and resource (Pipeworx's catalog), clearly distinguishing it from sibling tools like discover_tools and ask_pipeworx.

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

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

It provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the argument behavior (no args for full spread, pass topic to focus), giving clear context for when to choose this tool over 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 significant behavioral context beyond the annotations: ownership enforcement and the fact that the row is deactivated (not deleted), preserving historical events. This goes well beyond the structured hints.

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

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

Two sentences, front-loaded with the main action, then the ownership constraint, then the deactivation outcome. Every sentence earns its place with no redundancy.

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

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

For a simple one-parameter mutation tool, the description covers the operation, eligibility, and the deactivation result, even referencing recent_alerts. Annotations already handle idempotency and destructiveness, so nothing critical is missing.

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

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

The input schema already fully describes the single parameter as 'Subscription id (uuid) returned by subscribe.' The description simply says 'by id' without adding new meaning, so with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It uses a specific verb and resource, and the ownership note distinguishes it from subscription listing and creation tools.

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

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

It provides clear context that only your own subscriptions can be canceled and explains the deactivation behavior, but it does not explicitly name alternatives or state when not to use it.

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

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

The description goes beyond annotations by detailing the internal behavior: SEC EDGAR + XBRL fast path for financial claims, fall-through to grounded pipeline for others, percent-delta math, verdict types, and citation of evidence. It also notes that it 'replaces 4–6 sequential calls', offering efficiency context. 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 but well-structured, opening with example phrases to immediately convey usage, then purpose, routing, and return values. Every sentence adds value—no fluff or repetition of schema details. Length is justified by the tool's complexity.

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

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

For a tool with no output schema, the description thoroughly explains the return value (verdict categories, actual value, citation, reasoning) and covers edge cases like unsupported claims. It also explains the routing logic, making the tool's behavior complete and predictable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for 'tolerance_pct' by explaining it overrides claim wording, capping at 5, and suggesting 1–2 for hallucination detection. It also gives example claims for the 'claim' parameter, enriching schema 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 purpose: 'natural-language claim verification against authoritative sources' with a specific verb ('validate'/'fact check') and resource ('claim'). It distinguishes itself from sibling tools by focusing on verifying whether a user statement is factually correct and returns verdicts, unlike general search/ask 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 whenever the agent needs to check whether something a user said is factually correct', providing clear usage context. It also explains routing for company-financial vs other claims. However, it does not explicitly name alternative tools or specify when NOT to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context beyond the put-code key, such as no mention of error conditions or auth requirements. This is acceptable given the strong annotation coverage but adds little value.

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

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

The description is a single short sentence with no filler or repetition, making it very concise. However, it is a fragment lacking a verb, which slightly reduces clarity. Still, it is appropriately sized for a simple tool.

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

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

Given the tool's simplicity, the strong annotations, and the presence of an output schema, the description is minimally sufficient. It clearly indicates a single work record by put-code, but omits mention of the required orcid_id and any alternatives, leaving some gaps in usage context. It meets the minimum viable bar but could easily be enhanced.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions put-code but does not explain orcid_id, or clarify the role of either parameter beyond their names. The schema has examples but no property descriptions, so the description adds only marginal meaning for put-code and none for orcid_id.

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 'Single work record by put-code' clearly identifies a resource (work record) and the key identifier (put-code). It implicitly distinguishes from sibling 'works' by signaling a single record, though it lacks an explicit verb like 'get' or 'retrieve'.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'works' (plural) or other record types like 'education' or 'employment'. The description does not state any exclusions or context for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that the tool returns 'summaries' and includes 'put-codes', which is useful behavioral detail, but it does not describe pagination, ordering, or what constitutes a 'summary'.

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 short, which is efficient, but it is under-specified to the point of being vague. It reads as a fragment rather than a complete sentence, providing minimal actionable information. This is under-specification rather than purposeful conciseness.

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

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

While the tool has an output schema and strong annotations, the description itself is insufficient. It does not state that an ORCID iD is required, how the summaries are structured, or what 'put-codes' means in this context. The description alone would not allow an agent to confidently invoke the tool correctly.

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

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

Schema description coverage is 0%, and the description does not explain the 'orcid_id' parameter at all. It only mentions 'works' and 'put-codes', leaving the parameter semantics entirely to inference from the parameter name. The description fails to compensate for the lack of schema documentation.

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

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

The description identifies the resource ('Works (publication)') and mentions 'put-codes', but lacks an explicit verb like 'retrieve' or 'list'. It vaguely suggests returning summaries of publications for a person, but does not clearly distinguish from sibling tools like 'work' or 'record'.

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?

There is no guidance on when to use this tool versus alternatives. No mention of required context, prerequisites, or exclusions. The sibling tool 'work' likely serves a similar purpose, but no differentiation is provided.

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