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 declare read-only, open-world, and idempotent behavior. The description adds meaningful context beyond those: it routes to one of 5,708 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and is a single fast call. It also implies its limitation relative to the grounded variant by redirecting verbatim-evidence needs elsewhere.

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

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

The description is long, but dense and front-loaded with the most important guidance: 'PREFER OVER WEB SEARCH' and 'START HERE.' Every section adds value via domains, examples, or explicit routing to alternatives. Some minor redundancy exists between 'use whenever' and 'START HERE,' but the structure is logical and scannable.

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

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

Given no output schema, the description does enough by stating the return type (structured answer with citation URIs), the broad tool coverage, and the available escalation paths. It does not describe failure modes or unsupported-question handling, but for a default router with rich annotations, this is a minor gap. The description is sufficient for an agent to decide when to call and what to expect.

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

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

The schema already covers all 6 parameters with descriptions for each alias, so the baseline is satisfied. The description adds helpful examples and trigger phrases, but it does not define constraints on question format, length, or edge cases. The added value over the schema is moderate, not substantial.

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 names a precise action—routing a factual question to the right tool from a large verified-source pool and returning a structured answer with citations. It explicitly contrasts itself with ask_pipeworx_grounded and deep_research, making its distinct role clear. It also specifies the exact trigger conditions and domains, so an agent can tell it apart from web search and sibling tools.

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

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

The description gives explicit when-to-use guidance: prefer over web search, use for factual questions about real-world entities, and start here as the default entry point. It also gives when-not-to-use instructions by naming ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This leaves little to inference.

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

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

The annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds valuable live-state context: candidate routing improvements are enabled only when under test, none is active as of the listed date, and it is not a fallback but a full working router. It also promises identical response shape to ask_pipeworx. 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?

Front-loaded with the core identity and beta status, then usage, then current state. The exact tool count and retirement date add specificity without much bloat, and every sentence adds a distinct fact. Slightly denser than the minimum but well organized.

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

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

For a one-required-parameter router with annotations, it covers purpose, current behavior, and usage. It defers response details to ask_pipeworx ('same response shape') rather than describing them, and there is no output schema, but for invoking the tool correctly this is sufficient. The dynamic candidate state is explicitly explained.

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%: the six parameters are all documented as aliases for question, and question itself is fully described. The description adds no parameter-level detail, but none is needed beyond saying 'same arguments' as ask_pipeworx. Baseline 3 is appropriate because the schema carries the load.

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

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

The description identifies this as the beta version of ask_pipeworx and an identical universal router over 5,708 tools, which gives a concrete resource and scope. It also distinguishes itself from the stable sibling by noting it carries candidate routing improvements and is currently identical to ask_pipeworx. It does not fully define what 'universal router' produces, slightly relying on prior knowledge of 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?

States explicitly to use it exactly like ask_pipeworx when you want the newest routing, and contrasts it with the stable router whose results are used for merge decisions. It also tells the agent when it is safe to treat it as identical to the stable tool (no candidate active). This is explicit when/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?

Discloses the full success and refusal contracts: return fields on success and refusal_reason values on failure, plus explicit refusal behavior rather than fabricating answers. Annotations already mark it read-only/idempotent, and the description adds the guarantee that extraction uses only the tool result, which is substantial behavioral context beyond annotations.

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

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

Every sentence is load-bearing: differentiator, mechanism, return contract, refusal codes, usage boundary, and cost tradeoff. The most decision-relevant information is front-loaded and the refusal contract is compactly enumerated.

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

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

Even without an output schema, the description fully specifies the success shape, all refusal reasons, the cost comparison with ask_pipeworx, and the conditions under which to choose it. Nothing an agent needs to call or route to this tool is missing.

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

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

Schema coverage is 100% and the schema already documents the question parameter and all five aliases. The description adds no parameter-specific detail, but does not need to because the schema carries the semantics; this is the baseline case.

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

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

Opens with a specific differentiator — hallucination-resistant, high-stakes answer mode — and explains the exact mechanism: route, fetch, then extract only from tool result. It names the sibling ask_pipeworx and positions itself as the grounded variant, so an agent can distinguish them immediately.

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 it ('whenever an answer will be quoted, cited, or acted on') and gives the alternative ('prefer ask_pipeworx for casual lookups'). Also notes the cost tradeoff of one extra LLM call, making the selection decision fully informed.

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?

Even with readOnlyHint, openWorldHint, and idempotentHint set, the description adds substantial behavioral detail: account tiers, parallel decomposition, gaps[] never invented, contradictions[], citation resolvability, excerpting strategy, and latency expectations. It also clarifies the 'NOT open-web search' boundary, which is critical for agent expectations.

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

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

The description is long but densely packed with actionable information, and it front-loads the account requirement and the sign-in-based fallback before deeper mechanics. Minor redundancy with the schema's depth description prevents a 5, but every section earns its place 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?

With no output schema, the description fully covers the return packet shape: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers prerequisites, latency, and multi-hop behavior, making it complete for correct invocation and interpretation.

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

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

Schema coverage is 100%, so the schema already documents both parameters, but the description adds meaningful nuance: 'Broad/multi-part is fine — decomposition is the point' for question, and the practical effect of each depth value including paid-tier implications and contradiction scanning. This goes beyond baseline 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 states a specific verb ('research'), a precise resource ('Pipeworx's 1494 STRUCTURED data sources'), and the one-call parallel tool-routing mechanism. It explicitly distinguishes itself from open-web search and from ask_pipeworx, making sibling differentiation immediate.

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

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

It explicitly says when to use this tool ('broad/multi-part questions over structured data') and when not to, naming alternatives: use ask_pipeworx for single lookups, for breaking/current-news topics, and if not signed in. This leaves no ambiguity about tool selection.

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

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

Annotations already 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?

Beyond the minimal false annotation hints, the description discloses concrete behaviors: rate limit of 5 per identifier per day, free usage with no quota, claim_token returned without an account, and daily human review. This adds substantial transparency not apparent from annotations.

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

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

The description is long but every sentence earns its place: purpose, use cases, exclusions, token workflow, rate limits, and cost are all addressed with no redundancy. It is front-loaded with the primary function and progressively adds operational details.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (claim_token) and its lifecycle, covers exclusions, rate limits, content guidelines, and even tells users how to identify which tools are relevant. This is complete for a feedback submission 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. The description enriches meaning by explaining the claim_token round-trip workflow ('pass it back later to read whether it was fixed'), message length guidance ('1-2 sentences typical'), and instructing not to paste end-user prompts. This goes beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies specific feedback types (bug, feature, data_gap, praise) and explicitly distinguishes this from sibling tools like ask_pipeworx by scoping it to Pipeworx connection tools only.

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

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

Provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and when-not-to-use (tools from other MCP servers), even directing users to file elsewhere. It also explains how to use claim_token for later retrieval, giving complete context for use.

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

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

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?

Far beyond the read-only/idempotent annotations, it discloses return-field semantics, compatibility codes, pairing rules (unknown legs are never paired), temporal alignment, and dropped-comparison counters. It also explains that compatibility warnings can appear even when pairs are returned, which is non-obvious behavior.

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

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

Dense but organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. It is longer than average, but most sentences carry important behavioral or safety details; slight verbosity keeps it from a 5.

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 the response, and it covers leg prices, spread arrays, safety fields, codes, temporal alignment, and counters. For a complex 3-parameter comparison tool, an agent has enough to decide when to call it and what to expect back.

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

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

Schema already documents all three parameters and the override behavior, so baseline is 3. The description adds the mode-level semantics: topic mode auto-fetches matching events and explicit mode takes custom ticker+slug pairings, which is genuinely useful 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?

Description opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then specifies two modes and what the tool compares, making it distinct from nearby siblings like polymarket_edges or polymarket_arbitrage without needing their schemas.

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

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

The description gives clear context for when the spread is a real signal versus when it is not, and explicitly warns that pre-mapped topics can be non-tradeable. It does not, however, name alternative tools or say 'use X instead,' so it stops short of full alternative routing.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are supplemented with rich behavioral details: cascading internal lookups, graceful degradation if GLEIF/OpenFIGI unavailable, and explicit handling of unresolved identifiers under an 'unresolved' field. No contradictions.

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

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

The description is verbose but well-structured: starts with example queries, then usage guidance, then details per entity type, and ends with degradation behavior. Front-loaded with key purpose. A minor reduction for length, but each sentence adds value.

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

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

Given no output schema, the description compensates by explaining return structure (labels with source, unresolved field), covering all supported types, graceful degradation, and cascading behavior. For a tool of this complexity (multi-type, multi-source), it is exhaustive.

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

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

Schema coverage is 100% and the description adds substantial meaning beyond the schema. For 'company' type, it explains the cross-source identity spine (CIK, LEI, FIGI) and accepted input formats (ticker, CIK, ISIN, name). For 'drug' type, it adds RxCUI and citation details. This enriches parameter understanding significantly.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers required by other tools. It provides example queries and distinguishes itself from siblings like search and entity_profile by noting it replaces multiple manual 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 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to invoke. It implies when not to use (when IDs are already known) but does not provide an explicit 'do not use if' condition.

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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context that is not in the annotations: the meaning of 'could_not_verify' (the check did not happen and must not be interpreted as evidence) versus 'unsupported' (no source covers it), plus the routing to structured vs. grounded pipelines. This goes beyond the safety profile and explains failure semantics.

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

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

The description is longer than average but front-loaded with natural-language triggers and organized into logical paragraphs. The 'IMPORTANT for callers' callout is justified because it clarifies critical output semantics that are easy to misinterpret. Every sentence adds value, and the structure aids comprehension, so a 4 is fitting.

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 what the tool returns: verdict types, grounded/structured actual value with citation, and reasoning. It also covers edge cases (could_not_verify vs unsupported) and the two routing paths. For a complex tool with multiple behaviors, this is a complete description that leaves little 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 input schema already provides 100% coverage of both parameters with detailed descriptions (claim examples, tolerance_pct range and default). The tool description does not add additional parameter-level meaning beyond that; for instance, it mentions 'exact percent-delta math' but does not elaborate on the parameters themselves. Baseline 3 is correct because the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It uses specific verbs like 'check', 'verify', and 'confirm or refute', and explicitly distinguishes itself from sequential multi-step pipelines by noting it replaces 4–6 calls. This gives a specific verb+resource and differentiates 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?

The description provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details routing for company-financial claims versus other claims, but it does not explicitly name alternative tools or state when not to use this tool. This is clear context with no exclusions, so a 4 is appropriate.

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

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

Annotations already declare 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.