Orcid

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context: the external call to Anthropic when _apiKey is provided, the direct payment implication, and the exact per-model return structure. This goes beyond what annotations provide.

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

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

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

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

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

For a tool without an output schema, the description adequately explains what the tool returns. It also covers the core workflow (default model, optional Anthropic) and target use cases. It lacks explicit alternatives or when-not-to-use guidance, but the overall context is sufficient for a tool of this complexity.

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

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

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

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

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

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

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

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

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

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

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

Annotations already cover read-only, open-world, idempotent, non-destructive behavior. The description adds meaningful context beyond those: it routes to one of 5,767 tools across 1,506 sources, fills arguments automatically, and returns a structured answer with pipeworx:// citation URIs. It does not discuss rate limits or possible fallback behavior, but the annotation coverage lowers the burden.

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 the most important use guidance and full of actionable examples. Some phrasing is compressed and slightly awkward, and the example list is generous, but every section contributes to selection, invocation, or alternative routing.

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?

Complexity is high because this is a router tool with many possible domains, and the description covers purpose, input style, output/citation format, and alternatives such as grounded and deep_research. It does not explain the relationship to ask_pipeworx_beta or edge-case failure behavior, but for an agent deciding whether and how to call this tool it is nearly 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 describes the question parameter and all aliases, so the baseline is 3. The description adds value with natural-language trigger phrases and detailed example questions that are not all present in the schema, which helps an agent formulate valid input.

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

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

The description clearly states a specific action: ask a factual natural-language question and have Pipeworx route it to the appropriate tool among thousands of verified sources, returning a structured answer with stable citation URIs. It also differentiates from alternatives by naming ask_pipeworx_grounded and deep_research with distinct roles.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for factual/current/historical data, gives concrete query examples, and says 'STARD HERE for most questions'. It also gives explicit alternative routing: use ask_pipeworx_grounded for verbatim-evidence single answers and deep_research for broad multi-part questions.

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

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

Annotations already cover read-only, open-world, idempotent, non-destructive behavior, so the bar for added context is lower. The description enriches this by disclosing the experimental nature of the router, its live candidate-testing behavior, and the fact that no candidate is currently active. It also preempts confusion by stating 'Falls back to nothing—this IS a full working router,' clarifying it is not a wrapper with a fallback.

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

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

The description is three sentences, each carrying important operational information: the beta/identical nature, the current status with specific date evidence, and the guidance on when to use it. It is slightly dense, and the hardcoded retirement date may age poorly, but there is no fluff or repetition. The core usage condition is front-loaded enough.

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 single-question universal router with six schema-covered aliases and no output schema, the description is fully sufficient. It explains the tool's scope, its relationship to the stable version, current behavior, and the fact that it is fully functional rather than a stub. An agent has everything needed to invoke it correctly and set expectations about the response shape.

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

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

The input schema has 100% coverage for all 6 parameters, all aliases for the required 'question' field. The description says 'same arguments' but does not provide additional parameter-level meaning beyond what the schema already declares. This matches the baseline 3 for high schema coverage, as the description adds no semantics the agent cannot already derive from 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 identifies this as a beta universal router identical to ask_pipeworx, with the same 5,767 tools, arguments, and response shape. It specifies the resource (ask_pipeworx), distinguishes it from the stable version via its experimental routing improvements, and even names the sibling ask_pipeworx_grounded implicitly through the family. An agent knows exactly what the tool does and how it differs from its 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 explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It frames the stable ask_pipeworx as the comparison baseline and notes that results are compared to the stable router, making the intended choice clear. The absence of an active candidate further clarifies that it currently matches ask_pipeworx exactly, removing ambiguity.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior, and the description adds substantial context beyond that: the exact success return shape, the refusal contract with enumerated refusal_reason values, verbatim evidence, confidence, source, fetched_at, and the cost of one extra LLM call. 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?

Every sentence earns its place: the mode is front-loaded, followed by routing behavior, return/refusal contracts, use cases, and cost tradeoff. It is dense but not padded, and the crucial differentiator ('prefer ask_pipeworx for casual lookups') appears at the end as a decision rule.

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

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

There is no output schema, so the description correctly carries the burden of explaining return values and failure modes. It specifies success fields, refusal reasons, when refusals occur, and the cost tradeoff against the sibling. Combined with the high-coverage input schema and annotations, nothing essential is missing for an agent to invoke this safely.

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 six aliases all documented as a natural-language question and the question field explaining alias support. The description does not need to add parameter detail because the schema already carries the full meaning; baseline 3 is appropriate.

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

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

The description defines a specific, differentiated mode: 'Hallucination-resistant answer mode for high-stakes reads' that extracts answers 'using ONLY what the tool result contains.' It explicitly contrasts with ask_pipeworx by adding groundedness and an extra LLM call, so an agent can distinguish it from siblings without inspecting 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and gives the off-ramp: 'prefer ask_pipeworx for casual lookups.' This is clear routing logic, not just implied context.

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

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

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?

The description goes far beyond the annotations: account/auth requirements, latency expectations, gaps[] for unanswered facets, contradictions[] on standard/thorough, hop fields, resolvable citation_uri behavior, and semantic excerpting of large records. It also confirms the read-only, non-destructive nature implied by the annotations while adding concrete operational context.

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

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

The description is long but front-loaded: account requirements, scope, and primary alternatives appear first, followed by return behavior and latency. Some redundancy exists in repeated ask_pipeworx routing guidance, but for a complex tool the density is mostly purposeful.

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 findings packet shape, gaps behavior, contradiction handling, citation fetchability, latency, auth, and when not to use the tool. An agent has enough context to decide, invoke, and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no materially new parameter meaning: depth tiers, paid thorough, and contradiction behavior are already documented in the input schema. It reinforces the depth semantics but does not compensate beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in one call, and clearly contrasts itself with open-web search. It also distinguishes itself from ask_pipeworx for single lookups and live-news queries, so an agent can select it correctly.

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

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

Usage guidance is explicit and repeated where needed: use it for broad/multi-part structured-data questions; use ask_pipeworx instead for single lookups, breaking/current news, or when not signed in. Sibling alternatives are named with the conditions that route away from this tool.

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

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

Annotations already declare readOnlyHint=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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: it fans out across many sources, returns sources_used/sources_failed, soft-fails USPTO, treats empty FDA products as expected, and resolves private companies to resolved:false with notes. This goes far beyond the structured annotations.

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

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

The description is long but information-dense, with no filler; it front-loads examples and core intent before enumerating return fields and edge cases. It could be more structured for readability, but every sentence adds necessary behavioral or contextual detail for a complex 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?

Despite no output schema, the description thoroughly enumerates all return sections, input forms, failure modes, and expected empty-data cases. It also covers edge behaviors for names, CIKs, private companies, and API fallbacks, making it complete enough for correct invocation.

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

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

The schema already gives 100% description coverage, and the description adds practical meaning: accepted value shapes, zero-padded CIK requirement, name resolution behavior, and the fact that 'company' and 'ticker' are interchangeable. This supplements the schema without redundancy.

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

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

States a specific action and resource: 'full cross-source profile of a US public company in ONE parallel call,' backed by multiple user-intent examples such as 'brief me on Tesla.' It clearly distinguishes itself from single-pack lookups and named sibling-like behaviors, so an agent can recognize when to invoke it.

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 context: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It gives clear when-to-use guidance and identifies the main alternative pattern, though it does not explicitly contrast with sibling tools like deep_research or compare_entities.

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

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

The description 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial context beyond that: token-overlap matching, compatibility codes that can be non-empty even when pairs are returned, gross-vs-net spread disclosure, skipped leg counters, and the precise meaning of null temporal_alignment. 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 the tool is complex and has no output schema, so the detail is mostly earned. It is well structured with visible labels like TWO MODES, RESPONSE, and SAFETY FIELDS, and it front-loads the core purpose before the caveats. Some repeated phrasing could be tightened, so it is not a perfect conciseness score.

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

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

With no output schema, the description carries the full burden of explaining return values, and it covers leg-level prices, top_spreads_pp, compatibility warnings/codes, temporal alignment semantics, fees_note, skipped counters, and low_confidence_pairs. Minor edge cases like calling with no parameters at all are not spelled out, but an agent has enough to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds useful mode semantics: explicit ticker/slug parameters override the topic-mapped side, and both modes run the identical overlap matcher. This is genuine added value, but the schema already carries most of the parameter documentation burden.

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 precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It goes on to specify two modes, the nature of the response, and the tool's safety fields, making its purpose unambiguous and distinct from sibling tools.

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

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

It gives clear context for when to use the topic shortcuts versus explicit ticker/slug pairings, and it warns that most pre-mapped topics are not currently tradeable and that returned pairs can still carry compatibility warnings. It does not explicitly name alternatives or state 'use tool X instead,' so it stops short of full exclusionary 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?

The description extensively discloses behavioral traits beyond annotations: cross-source identity spine, fallback degradation when GLEIF/OpenFIGI are unavailable, ambiguity handling via figi_candidates, explicit unresolved field, and source labels for identifiers. It also reveals internal cascading through multiple endpoints, which annotations do not convey.

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

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

The description is long and dense, but almost every sentence carries distinct operational value, including edge cases and naming constraints. It is front-loaded with the core purpose, though a more structured layout with bullets would improve skimmability. The length is justified by the tool's multi-source complexity.

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

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

With no output schema, the description carries the burden of return-value disclosure, and it does so thoroughly: it lists returned identifiers (CIK, ticker, company_name, LEI, FIGI, RxCUI), explains ambiguous-result behavior (figi_candidates), and notes unresolved identifiers. All necessary input semantics, types, and edge cases are covered.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning beyond the schema. For the 'value' parameter, it offers crucial guidance: pass the ENTITY NAME ONLY, use the issuer exactly as printed for bonds, and never include trailing security-class words. It also explains how different identifier types (ticker, CIK, ISIN) map to the same parameter.

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

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

The description states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes this from sibling tools by focusing on name-to-ID resolution, with concrete examples like 'What's the ticker for…' and 'find the CIK for…'.

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 an explicit directive: 'Use FIRST whenever you have a name but need an ID,' which clearly indicates when to invoke this tool. It does not name alternative tools or explicitly state when not to use it, but the supported input types and the 'need an ID' condition provide sufficient context.

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

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

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