Rcsb Pdb

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

Given readOnlyHint=true and other annotations already establish safety, the description adds valuable context: the default free model, the requirement for a _apiKey to probe Anthropic, the direct pass-through to api.anthropic.com (and associated cost), and the per-model return structure. This goes well beyond the annotations.

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

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

The description is four sentences, each earning its place: what it does, default/free behavior, cost caveat, return format, and use cases. It is front-loaded with the core purpose and avoids fluff or repetition of schema details.

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

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

With 4 parameters, no output schema, and strong annotations, the description fully compensates: it specifies the return shape (per-model {score, confidence, signals, raw_response} + combined view), mentions multi-model invocation, and covers cost implications. No critical gaps remain.

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

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

Schema coverage is 100% with good descriptions for each parameter. The tool description adds value by explaining the default model for the `models` parameter, clarifying that `_apiKey` is only needed for 'anthropic', and giving realistic examples for `entity` and `context`. This goes beyond the schema without being redundant.

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 ('Probe'), identifies the resource (LLMs), and states exactly what it produces (visibility score 0-100 per model). It also differentiates from siblings like deep_research and ask_pipeworx by focusing on LLM knowledge scoring rather than general research or Q&A.

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

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

The description explicitly lists concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which signals when to reach for this tool. However, it does not explicitly say when not to use it or name alternative tools, so it falls just short of the top score.

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

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

Annotations already cover read-only/idempotent safety. The description adds valuable behavioral context: routes to one of 5,439 tools, fills arguments, returns structured answers with stable citation URIs, and mentions limitations by directing to the grounded variant for verbatim evidence. No contradictions.

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

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

The description is long but dense and front-loaded with the key directive ('PREFER OVER WEB SEARCH'). Every sentence contributes useful information, though a slight trim could improve conciseness without loss.

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

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

Given the tool's complexity and absence of an output schema, the description is remarkably complete. It explains what it does, when to use it, what it returns (structured answer with citations), and how it differs from alternatives. It also notes compatibility with every tier and speed.

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%: all six parameters are documented as aliases for the single 'question' field, with clear descriptions and examples. The description adds example queries but does not materially increase parameter clarity beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions by routing to a large collection of verified sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use the tool: for current or historical data across many domains, and even when web search could answer. It also specifies when to step up to ask_pipeworx_grounded or deep_research, and provides concrete example queries.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that candidate routing improvements may be active live, that currently no candidate is active so it matches ask_pipeworx exactly, and that it is a full working router rather than a fallback. This adds significant behavioral context not available in 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 efficiently structured and every sentence earns its place: it conveys the beta nature, current status, usage instructions, and a caveat that it is a full working router. It is front-loaded with the key 'Beta version' concept and avoids redundancy.

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

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

For a beta router with no output schema, the description provides complete context: it explains the identical interface to ask_pipeworx, the live experimental nature, and the comparison mechanism. This is sufficient for an agent to decide to invoke the tool and set expectations about behavior.

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

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

The schema has 100% coverage, with all six parameters being well-described aliases for 'question'. The description adds no new parameter-specific meaning beyond noting 'same arguments' as ask_pipeworx, so the schema already fully handles parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router that selects among 5,439 tools, and explicitly distinguishes it from the stable ask_pipeworx by noting it sits on the experimental edge. This provides a specific verb+resource and differentiates it from its sibling.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. This gives clear when-to-use guidance and implicitly identifies ask_pipeworx as the stable alternative, satisfying the 'when/when-not/alternatives' criterion.

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

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

Adds rich behavioral detail beyond the annotations: extracts only from tool results, returns explicit refusal reasons, and incurs an extra LLM call. The annotations already indicate readOnly and idempotent, and the description complements them without contradiction.

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

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

The description is front-loaded with the core purpose, then efficiently covers mechanism, return shape, refusal reasons, use cases, and cost tradeoff. Every sentence earns its place with no fluff.

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

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

For a complex meta-tool, the description covers all necessary aspects: return format, refusal reasons, recommended use cases, cost implications, and sibling distinction. It fully compensates for the lack of an output schema.

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

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

Schema coverage is 100% with all parameters documented as aliases for the question. The description does not add parameter-specific meaning, so the baseline 3 is appropriate.

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

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

The description clearly states it is a hallucination-resistant answer mode for high-stakes reads, explaining the full routing and extraction mechanism. It explicitly distinguishes from sibling ask_pipeworx by emphasizing grounded evidence and explicit refusals.

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 (answers quoted/cited/acted on, must not invent facts) and when-not-to-use (casual lookups prefer ask_pipeworx), including the cost tradeoff of an extra LLM call. Names the alternative directly.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, so the safety profile is covered. The description adds useful conceptual context about biological assemblies differing from asymmetric units, but doesn't disclose additional behavioral traits like error handling or default assembly selection.

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

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

The description is two sentences long and relatively concise. The first sentence is slightly clunky with quotes, but the second sentence adds clear usage guidance without superfluous detail.

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 2 parameters and an output schema, the description is adequate but leaves gaps. It explains the core purpose and usage, but does not clarify assembly_id semantics or default behavior when assembly_id is omitted. The output schema likely covers return values, so that is not a major issue.

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 implicitly references pdb_id via placeholders like '[pdb_id]' and 'PDB entry', but does not explain the meaning or usage of assembly_id. The description provides only minimal parameter context.

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

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

The description states the tool 'fetch[es] a biological assembly record', clearly specifying the action and resource. It also distinguishes biological assembly from the crystallographic asymmetric unit, setting it apart from sibling tools like 'structure'.

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: 'Use when you need the actual functional form of a protein (dimer / tetramer / etc.) rather than the crystal contents.' This gives clear when-to-use context, though it doesn't explicitly name an alternative 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?

The description richly discloses behavioral traits beyond annotations: low-confidence short-circuit with status suppression, closed/inactive market handling, illiquid wide-spread flag, resolution-rule parsing, and parallel fan-out. Annotations already declare readOnly/idempotent/openWorld, and the description adds substantial non-redundant context without contradiction.

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 purpose and usage, then organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is long but dense and well-structured; each section serves a distinct need for agent decision-making. Not a 5 because some fan-out examples could be trimmed without loss of core meaning.

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

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

With no output schema, the description takes on full responsibility for explaining return values, and it succeeds: it details response shapes (result.market, result.analysis, result.evidence), resolver contract (market_match_confidence, alternatives), parent_event extractor, news fallback fields, safety statuses, and resolution-rule risk. Comprehensive for a complex tool.

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

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

Schema coverage is 100% with detailed parameter descriptions, so baseline is 3. The description adds fan-out examples and response shapes, but these do not materially enrich the meaning of the three parameters beyond what the schema already provides. The description does not need to compensate much here.

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+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It details the process (resolve, classify, fan out, return evidence packet + comparison) and clearly differentiates from siblings by focusing on Polymarket bets with unique response structures like market_vs_model comparison.

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

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

Provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool, but it does not explicitly name alternatives or describe when-not-to-use cases, stopping short of a 5.

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

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

The description adds rich behavioral context beyond annotations: it explains off-calendar fiscal year handling, sorting by primary metric, return format (paired data + pipeworx:// URIs), and performance (replaces 8–15 sequential lookups). No contradiction with readOnly/idempotent annotations.

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

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

The description is dense but well-structured: front-loaded with natural language triggers, followed by the core purpose, type-specific details, sorting behavior, and return format. Every sentence contributes unique value with no fluff or repetition.

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

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

Despite no output schema, the description covers what data is returned (paired data + citation URIs), sorting behavior, entity types, fiscal year handling, and when to use. It is complete for a tool of this complexity, addressing both input semantics and output expectations.

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

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

Schema has 100% coverage, but the description enriches both parameters: 'type' is explained with enum semantics and data sources, and 'values' gets examples (tickers/CIKs, drug names) and constraints (2–5 items). This goes well beyond the schema's short descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, using specific examples like 'Compare X and Y' and 'which is bigger'. It distinguishes from sequential single-pack lookups, making the purpose unambiguous.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also details what data is pulled for each type (company vs drug), enabling appropriate selection based on the user's query.

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 significantly exceeds the annotations (readOnly, openWorld, idempotent, non-destructive) by disclosing account requirements, paid tiers, parallel decomposition, explicit gaps[] to avoid invented answers, return format details (verbatim evidence, confidence, citations), contradiction scanning, and expected latency. It also explains the 'not open-web search' limitation, adding crucial context not inferable from annotations alone.

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

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

The description is long but densely packed with necessary caveats and behavioral details; it is front-loaded with account requirements and the key alternative (ask_pipeworx). Each clause earns its place, though it could be slightly restructured for readability (e.g., clearer sectioning). No redundant filler or tautology.

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?

Without an output schema, the description compensates thoroughly by describing the findings packet (verbatim evidence, confidence, source, fetched_at, citations), gaps[], contradictions[], hop field, and excerpting behavior. It also covers latency, iteration modes, and limitations, making the tool's behavior fully foreseeable for an agent despite the lack of structured output definitions.

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 both params are described in the schema, but the description adds meaningful nuance: it clarifies depth levels with behavioral differences (quick single-hop, standard gap recovery, thorough iterative + contradictions), ties 'thorough' to a paid plan, and explicitly states the question parameter accepts broad/multi-part natural language. This goes beyond the enum labels and schema descriptions, though much of it is still implied by the schema.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' in one call, explicitly distinguishing it from open-web search. It also contrasts with sibling tools like ask_pipeworx by noting it is best for broad/multi-part questions, giving a specific verb and resource scope.

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

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

The description provides explicit guidance on when to use deep_research ('best for broad/multi-part questions'), when not to use it (single lookups, breaking/current news), and names alternatives (ask_pipeworx). It also covers account/tier requirements and second-hop iteration behavior, making selection criteria unambiguous.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context about the return format (top-N tools with full input schemas and curated examples) and notes that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations without contradicting them.

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

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

The description is slightly long due to the domain list, but every sentence serves a purpose: opening purpose, usage conditions, return details, and calling directive. It is front-loaded with the core action and maintains logical flow. The length is justified by the need to convey broad applicability.

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

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

Given there is no output schema, the description fully compensates by explaining exactly what is returned (names, descriptions, full input schemas, curated examples) and that results are directly callable. It also covers when to use the tool and what it doesn't do (single-answer retrieval). This makes the tool's behavior and outputs clear without additional structured metadata.

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 each parameter (query, q, task, search, description, limit) has a clear schema description. The tool description adds the concept of 'top-N' and lists example domains, but these are largely redundant with the schema's examples and property descriptions. It does not meaningfully deepen parameter understanding beyond the schema.

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

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

The description opens with a clear statement: 'Find tools by describing the data or task.' It specifies the tool's role as a discovery/browsing mechanism, distinct from sibling tools that perform specific tasks. The list of domains (SEC filings, FDA drugs, etc.) further clarifies scope.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and even recommends 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to prefer 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?

Beyond the readOnly/idempotent annotations, the description discloses notable behaviors: fan-out across multiple data sources, specific return fields, patent API sunset with soft-fail, and GDELT→GNews fallback. No contradictions with annotations exist.

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

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

The description is longer than average but every clause packs useful information. The example queries are somewhat repetitive yet help clarify the tool's scope. It is front-loaded with the core purpose and then details outputs and constraints; no fluff remains.

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 explaining return values. It enumerates key output fields (cik, filings, fundamentals, patents, news, LEI) and notes limitations. It could be more explicit about details like filing date ranges, but overall it is adequate for the tool's complexity.

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

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

Schema description coverage is 100% for both parameters (type and value), and the description reiterates the same information without adding new semantics. It does clarify zero-padded CIK formatting, but this matches the schema descriptions, so no significant value-added beyond baseline.

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

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

The description clearly states the tool creates 'full cross-source profile of a US public company in ONE parallel call' and provides multiple example queries. It distinguishes itself from sibling tools by explicitly noting it should be preferred over chaining single-purpose lookups, and mentions resolve_entity for name input.

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 usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and states that names are not supported, directing users to resolve_entity first. This clearly defines when to use this tool versus alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and stale context, which goes beyond the annotations. It does not contradict them, and the 'Delete' wording is consistent.

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

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

The description is two sentences, front-loaded with the operation, and every phrase earns its place. It is concise without sacrificing essential guidance.

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

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

For a simple one-parameter tool with strong annotations, the description covers purpose, usage, and relationship to siblings. No output schema exists, but none is needed for a deletion operation, and the description is complete for 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 description coverage is 100%, so the parameter 'key' is already documented as 'Memory key to delete.' The description adds 'by key' but this is redundant with the schema. No additional parameter nuance is provided.

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: 'Delete a previously stored memory by key.' The verb 'Delete' and resource 'previously stored memory' are specific, and this distinguishes it from sibling tools like remember (store) and recall (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?

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also pairs with remember and recall, but does not explicitly state when not to use it, so it falls just short of full 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds process details: fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format, as well as noting that the output is a single text blob. This is useful 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 concise and well-structured, with a clear opening sentence, a brief process explanation, and a useful 'Useful for' list. Every sentence serves a purpose, though it could be slightly tighter.

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 read-only tool with full schema coverage and strong annotations, the description explains the purpose, process, output format, and use cases. It does not discuss error handling or edge cases, but these are not essential 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 description coverage is 100%, with both url and max_links clearly described. The description does not add any parameter-specific semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states exactly what the tool does: generates a production-ready llms.txt file for any URL, with a clear verb+resource+output format. It also distinguishes itself from siblings like scan_competitor_ai_presence by focusing on file generation rather than visibility checking.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting llms.txt for your own project, or auditing a competitor. It does not explicitly name alternative tools or say when not to use it, but the use cases make the intended context 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 readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds context about the entity type (non-polymer, small molecule, cofactor, ion, drug) but does not disclose additional behavioral traits like error handling, rate limits, or return behavior beyond what annotations imply.

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

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

The description is somewhat repetitive, opening with two alternative quoted phrases ('Ligand / cofactor / drug bound to [pdb_id]' / 'small molecule in [PDB entry]') that overlap with the main explanation. It is not excessively long but could be more streamlined. This warrants a middle 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?

Given that the tool has only two parameters, read-only annotations, an output schema, and a clear domain context (co-crystal structures, SBDD), the description provides sufficient information for a simple fetch operation. It explains the parameter roles and usage context, making it reasonably complete without needing to detail return values.

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

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

The input schema has 0% description coverage, so the description compensates by explaining pdb_id as a PDB entry and ligand_id as the bound small molecule/ligand. It clarifies the roles of both parameters in context, though it doesn't specify exact formats or code conventions (e.g., 4-character PDB code or HET code), preventing a 5.

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

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

The description clearly states the tool fetches a non-polymer ligand record (small molecule, cofactor, ion, or bound drug) for a PDB entry, using a specific verb ('fetch') and resource ('non-polymer ligand record'). It distinguishes from siblings by explicitly highlighting 'non-polymer' and listing entity types, contrasting with potential polymer-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?

The description provides a clear use case: 'Use to inspect what's bound in a co-crystal structure — common in drug discovery / SBDD.' This gives context for when to use the tool, but it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds meaningful behavioral context: it scopes results to 'the caller's' subscriptions and enumerates the exact return fields (id, type, params, created_at, last_fired_at, fire_count). This goes beyond the annotations' generic safety profile.

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, no fluff. The first sentence states the purpose and return fields; the second gives actionable usage guidance. Every word earns its place, making it highly concise and well-structured.

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

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

For a simple list-with-one-optional-parameter tool, the description completely covers what the tool does, what it returns, and why you'd use it. No output schema is needed given the explicit field list. No missing context is apparent.

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

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

Schema description coverage is 100% for the single parameter include_inactive, so the schema fully explains its meaning. The tool description does not add extra detail about the parameter, but the baseline 3 is appropriate given the schema handles semantics.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions' with a specific verb and resource. It further distinguishes itself from siblings by listing the exact fields returned, confirming its role as a read-only listing tool compared to subscribe/unsubscribe.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' (to avoid duplicate subscriptions) and 'to find an id to cancel' (for unsubscribe). While it doesn't explicitly mention when not to use or alternative tools, the guidance is clear and contextually relevant.

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 only default false values, so the description carries the transparency burden. It discloses rate limiting (5 per identifier per day), that it is free and doesn't count against tool-call quota, and that the team reads digests daily. It does not detail data handling or retention, but for a feedback submission tool this is sufficient context beyond annotations.

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

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

The description is long but front-loaded and information-dense. Every sentence serves a purpose: purpose statement, usage categories, exclusion boundary, identification tip, content guidance, roadmap impact, and rate limit. No fluff or repetition; the structure flows logically from what → when → exclusions → how → consequences.

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

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

For a feedback tool with three parameters and no output schema, the description covers all necessary context: selection criteria, content expectations, scope limitations, and constraint (rate limit). It tells the agent everything needed to correctly invoke the tool and avoid misuse, so no further information is required.

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?

All three parameters have full schema descriptions, so baseline is high. The description adds practical guidance for the message parameter: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which is not captured in the schema. It also reinforces type enum meanings, making parameter semantics richer than schema alone.

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

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

The description opens with the specific verb-resource pair 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly distinguishes this feedback tool from the query/analysis sibling tools. It also enumerates the exact categories (bug, feature/data_gap, praise) that map to the input schema, making the tool's purpose unmistakable.

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

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

Usage guidance is explicit and well-structured: it states when to use (bug, feature/data_gap, praise) and, crucially, when not to use (for tools from other MCP servers, with direction to file elsewhere). The clarification 'Pipeworx tool names are the ones this connection lists' provides a concrete disambiguation rule.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses the data source ('derived from CF analytics-engine'), privacy ('no PII'), output granularity ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h'). This adds meaningful behavioral context and does not contradict any 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 core purpose, lists concrete use cases, and adds key details (data source, privacy, caching) in a compact form. Every sentence adds value, with no redundant filler.

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

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

For a simple read-only tool with one parameter and no output schema, the description is complete. It explains what is returned (top tools, packs, call volume), the data source, privacy guarantees, and caching behavior. No crucial context is missing for an agent to effectively use the tool.

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

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

The single parameter 'window' is fully covered by the schema description (100% coverage), including its enum values and semantic explanation of shorter vs. longer windows. The tool description only mentions the window in passing ('24h, 7d, or 30d') and adds no extra meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description starts with 'What other AI agents are calling on Pipeworx right now', clearly stating the tool's purpose as a read-only aggregator of trending tool usage. It specifies the output (top tools, top packs, total call volume) and distinguishes from siblings like ask_pipeworx or discover_tools, making it uniquely identifiable.

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents' needs. It gives clear context for when to use the tool, though it does not explicitly mention alternative tools or when not to use it, which prevents a perfect score.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behavioral traits: the 3pp deviation threshold, placeholder filtering with 20% cap, Jaccard similarity ≥0.30, and the fill check cautioning that realizable_edge_pp ≤ 0 means the arb is not tradable. This is rich, safety-relevant 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?

Although long, the description is tightly structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and no filler. Each sentence adds operational guidance, and the core function is front-loaded. The length is justified by the tool's multifaceted behavior.

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

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

With no output schema, the description explicitly defines the response shape (opportunities[] with fields, partition_check with sum_yes_prices, gap_from_1, etc.) and covers edge cases like skipped_low_similarity, placeholders_filtered, and realizable_edge. It is self-sufficient for an agent to invoke and interpret results.

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

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

The schema provides good descriptions for both parameters, but the tool description adds operational depth—'event' mode 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check', while 'topic' mode 'searches related events...flattens markets'. This significantly exceeds the schema's one-liners and clarifies how each parameter changes behavior.

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

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

The description opens with a specific verb+resource ('Find arbitrage opportunities on Polymarket') and immediately distinguishes itself from siblings by naming the two detection mechanisms (monotonicity violations, partition-sum checks). It also clearly differentiates the three invocation modes (trending_scan, event, topic), 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 instructs when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It also names an alternative tool ('For custom sizing use polymarket_fill_risk') and explains why cross-event mode is useful ('catches ...by May 31 vs ...by Jun 30 patterns'). This is exemplary usage guidance.

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

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

Beyond annotations (readOnly/idempotent), the description discloses caching behavior ('Cached 1h at the KV level'), response structure (by_segment, _diagnostics), and interpretation warnings ('your edge may already be in the price'). It also explains why segments can be empty via funnel counters, which is valuable behavioral 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?

While front-loaded with a clear purpose, the description is an extremely dense single paragraph with many model-specific details (e.g., alpha values, placeholder filters) that are not necessary for tool selection. It could be better structured for quick parsing.

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 thoroughly explains the response format (by_segment, fed_candidates, _diagnostics), the meaning of each segment, and the knobs affecting them. It also covers caveats like the 24h-move warning and overround adjustments, making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline 3. The description adds extra meaning by grouping 'TRADEABLE-EDGE KNOBS' and explaining interactions (e.g., min_kelly doesn't filter partition arbs because parent-level kelly is 0). This goes beyond the schema's per-parameter descriptions.

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

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

The first sentence clearly states: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource+output, and the phrase 'what should I bet on today' frames the intended use. It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement rather than pure cross-market 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 clearly implies the use case ('what should I bet on today') and describes when results appear (e.g., Fed bets excluded due to unreliable signal). However, it does not explicitly name alternative tools or state when NOT to use this tool, so it stops short of a 5.

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

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

Annotations already establish readOnly/openWorld/idempotent/non-destructive, but the description goes far beyond that. It details the response structure (tracked[], expired[], snapshot_dates[]), signed edge values (negative = SELL YES), decay computed on absolute values, the 60-day snapshot TTL, cache-miss data gaps, and daily-close vs intraday semantics. This is exactly the kind of behavior an agent needs to interpret results correctly.

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 extremely dense and well-organized with explicit sections (Args, RESPONSE, LIMITS). The purpose is front-loaded in the first sentence, and every subsequent sentence contributes unique information about output semantics or limitations. 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?

There is no output schema, so the description fully carries the burden of explaining return values. It thoroughly documents all three arrays (tracked, expired, snapshot_dates), their fields, the trend categories, the decay metric, and historical limitations. Combined with the rich annotations and clear schema, the description is complete for correct tool invocation and result interpretation.

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

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

Schema description coverage is 100%, and both parameters (days, window) already have clear descriptions with defaults and clamps. The description's 'Args' line simply restates the defaults and max without adding any new meaning, constraints, or cross-parameter relationships. 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 opens with a specific verb+resource+goal: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly frames the question it answers ('how long has this edge existed and is it shrinking?'). This clearly differentiates it from sibling tools like polymarket_edges, which presumably focuses on current edges.

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

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

The description provides strong context for when to use the tool: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)' implies historical analysis is needed. It mentions it is 'built from daily polymarket_edges snapshots,' which contrasts with current-edge tools. However, it does not explicitly name alternatives or state when-not-to-use, so it stops short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses detailed behavioral traits: the tool walks the order-book ladder, returns verdicts like 'clean|degraded|cannot_fill,' identifies thin_legs and forced_directional_risk, and explains partial-fill risks. It also states parameter clamping (10–1,000,000) and default side selection, adding significant 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 dense and information-rich, but it is presented as one long, unbroken paragraph. Every sentence carries substantive value, yet the lack of bullet points or section breaks makes it harder to parse quickly. It is appropriately sized for the tool's complexity but not optimally structured.

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

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

Given there is no output schema, the description meticulously enumerates return fields for both single-market and basket modes, including top_of_book, vwap_fill_price, slippage_pp, capture_ratio, and thin_legs. It also explains defaults, clamping, and the dominant loss mode, making the tool fully comprehensible for an agent deciding whether and how to invoke it.

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

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

Although the schema already describes all four parameters, the description substantially enriches their semantics. It explains that market and event are mutually exclusive modes, that size_usd interprets differently in single-market vs basket mode, and that side has mode-specific valid values and defaults. This goes far beyond 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?

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which precisely states what the tool does. It also distinguishes itself from siblings by explaining it is a pre-trade risk check for polymarket_arbitrage and polymarket_edges signals, explicitly naming those tools.

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

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

The description gives explicit when-to-use guidance: '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, warning about theoretical overround and partial basket fills converting arbs into unhedged directional positions, which is clear contextual 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 goes far beyond annotations. It details the two modes, the response structure (leg-by-leg prices, top_spreads_pp), and the safety fields: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs 0), temporal_alignment, and skipped_cross_type/subtype counters. It also discloses the tool's behavior of flagging non-equivalent bet shapes and temporal mismatches, ensuring the agent knows when output is meaningful. No contradiction with readOnlyHint=true.

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

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

Although long, the description is well-structured and densely informative. It front-loads the core purpose, then uses bold labels (TWO MODES, RESPONSE, SAFETY FIELDS) to organize details. Every sentence serves a purpose: explaining modes, response fields, safety conditions, and caveats. For a tool with this complexity, the length is justified and not wasteful.

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

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

With no output schema, the description carries the full burden of explaining return values and behavior, and it does so thoroughly. It describes the response structure (leg-by-leg prices, matched spread with top_spreads_pp), the safety fields and their triggering conditions, temporal alignment, and skip counters. It also includes practical caveats about the rarity of tradable spreads, making it complete for an agent to understand when and how to 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 all three parameters (100% coverage), so baseline is 3. The description adds meaningful context beyond the schema: it explains the two modes, how topic maps to pre-defined shortcuts, and how explicit parameters override the topic-mapped side. It also clarifies the semantics of the topic values and provides examples, which helps the agent select and construct parameters correctly.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (computes spread), the resources (Kalshi, Polymarket), and the distinguishing feature (same resolving question across venues). It also differentiates from sibling tools like polymarket_arbitrage by focusing specifically on inter-venue spreads.

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

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

The description provides clear context on when to use the tool: to compare prices across venues when bet shapes are equivalent. It explains two modes (topic shortcuts vs explicit pairings) and warns about limitations (pre-mapped topics often not tradeable, compatibility_warning conditions). However, it does not explicitly name alternative tools or state 'use this when X, not when Y', so it stops short of full exclusion guidance.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds value by specifying the exact return content (sequence, source organism, UniProt cross-references, GO annotations), which goes beyond the annotations. It does not cover error cases or rate limits, but these are not critical for a simple fetch.

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 starts with intuitive example queries, then states the action and return fields, and ends with a usage tip. 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?

Given the tool's simplicity (2 plain string params) and the presence of an output schema, the description is complete: it explains what the tool does, what it returns, and when to use it. It lacks only edge-case details, which are not essential for a metadata fetch 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 has zero parameter descriptions (0% coverage), but the description's example query formats ('Chain [N] of PDB [ID]' and 'sequence of chain in [pdb_id]') effectively map pdb_id to the PDB entry and entity_id to a chain number. This compensates for the missing schema info, though it leaves some format details implicit.

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 states it fetches polymer-entity metadata for a specific PDB entry, with a specific verb ('fetch'), resource ('polymer-entity (protein/DNA/RNA chain) metadata'), and scope. It distinguishes from siblings like 'assembly' and 'ligand' by emphasizing drill-down into one chain.

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 advice: 'Use to drill into one chain of a multi-chain structure.' However, it does not mention when not to use it or name alternative tools, so it lacks full exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context beyond annotations: scoping to identifier type and the 'omit key to list all' behavior. No contradiction with annotations.

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

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

Three sentences, front-loaded with the core action. Each sentence contributes meaningful context (function, usage, scoping) without redundancy.

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

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

For a low-complexity tool with one optional parameter and read-only annotations, the description covers function, usage, scope, and sibling relationships. It does not mention edge cases like missing keys, but the simple nature makes this adequate.

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

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

Schema coverage is 100% for the single optional key parameter, and the schema description already includes 'omit to list all keys'. The description adds examples of key content but does not significantly go beyond the schema.

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

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

The description explicitly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)' with a specific verb and resource. It also distinguishes from sibling tools by referencing remember and forget.

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

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

It gives clear when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch' and points to alternatives (remember/forget) via pairing. This provides explicit context and exclusions.

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

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

The description explicitly says mark_read:true flags events as read, which mutates state, but the annotations declare readOnlyHint:true. This is a direct contradiction, undermining the reliability of the safety 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?

The description is three sentences, starts with the main purpose, and packs useful details without excessive verbosity. The final sentence is slightly long but still 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 description covers return fields, filtering, mark_read behavior, polling suitability, and an alternative access method. With no output schema and 5 optional parameters, it provides enough context for typical use, though it doesn't explain 'source' or 'citation_uri' in depth.

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

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

Schema coverage is 100%, but the description adds a concrete example for 'type' (sec_8k) and clarifies that 'since' is an ISO timestamp. The behavior of mark_read is also reinforced, providing slight value beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' clearly specifying the verb and resource. It distinguishes itself from sibling tools by focusing on reading fired alerts, whereas siblings manage subscriptions or perform other actions.

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 that it returns most recent alerts, supports filtering by type and since, and notes that polling works fine. It also mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly name sibling tools or conditions for when to use this tool 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 the readOnly/idempotent annotations, the description discloses important behaviors: GDELT→GNews fallback on rate limits or 5xx, USPTO soft-fail due to PatentsView sunset, parallel fan-out, and the structured return shape (changes[] grouped by source, total_changes, citation URIs). This is rich, non-obvious behavioral 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 a single dense paragraph with no fluff, and the query examples front-load purpose. The length is justified by the multi-source behavior, though a bulleted list or short sub-sections could improve 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?

Despite having no output schema, the description explicitly states the return structure and data grouping. It covers source fallbacks, failure modes, accepted since formats, and points to an alternative tool, making it fully self-contained for a complex fan-out tool.

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

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

The input schema already documents all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds example relative shorthands ('7d', '3m') and typical monitoring advice ('30d' or '1m'), but no substantial new semantics 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?

Description opens with concrete query phrases, then states core function with a specific verb ('change feed for a company') and explicitly names the three fan-out sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from entity_profile, preventing sibling confusion.

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 ('What's new with X', 'latest on Y') and the time-window context. It clearly redirects to entity_profile when the static profile is needed, giving a direct alternative and when-not-to-use guidance.

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

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

Annotations already declare idempotentHint and non-destructive behavior. The description adds valuable context beyond annotations: key-value scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. It does not detail overwrite semantics, but the idempotent annotation covers repeated writes.

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

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

The description is five tightly focused sentences: purpose, when to use, storage model, retention policy, and companion tools. Every sentence adds a distinct piece of actionable information with 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 two-parameter set operation with no output schema, the description is remarkably complete. It covers the operation's purpose, triggers, scope, persistence behavior, and how to retrieve or delete data. No critical usage context is missing.

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

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

Schema coverage is 100%, and both parameters have descriptive schema text. The tool description reinforces the key-value model and gives examples of what to store, but these examples largely mirror the schema's own examples ('target_ticker', 'user_preference'). No additional parameter-level meaning is added beyond the schema.

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

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

The description opens with 'Save data the agent will need to reuse later' — a specific verb and resource — and clarifies scope with 'across this conversation or across sessions.' It also distinguishes itself from siblings recall and forget by positioning remember as the write operation for persistence.

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

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

It explicitly states when to use the tool: 'Use when you discover something worth carrying forward' and gives concrete examples like ticker, address, or preference. It also names companion tools: 'Pair with recall to retrieve later, forget to delete,' providing clear context versus alternatives.

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

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

Annotations already indicate read-only/idempotent/non-destructive traits. The description adds valuable context: each call cascades through internal lookup endpoints, returns specific citation URIs, and auto-disambiguates inputs. This goes 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 relatively long but every section earns its place: usage examples, supported types, return details, and internal note. It is front-loaded with real user queries, making it efficient despite length.

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

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

The tool has two entity types with different output schemes and no output schema, so the description carries a heavy burden. It thoroughly covers each type's inputs, outputs, and internal behavior. Missing edge-case behavior (e.g., no match found) but overall complete.

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

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

Schema coverage is 100% with descriptions for both parameters, but the description enriches meaning by explaining accepted formats (ticker, CIK, name for company; brand/generic for drug) and disambiguation behavior. This adds value beyond the schema.

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

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

The description clearly states the tool resolves names to official identifiers, with specific examples (ticker, CIK, RxCUI) and supported types (company, drug). It distinguishes itself from siblings like search or entity_profile by focusing on identifier resolution.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID' and provides concrete query examples. It does not explicitly name alternatives or when-not-to-use conditions, but the guidance is clear and directive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the probing process (via ai_visibility_check), ranking logic, and output structure (ranked list with score, confidence, signal density). This goes beyond the annotations while staying consistent.

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, each serving a distinct purpose: purpose, mechanism, use case, and return value. It is front-loaded and free of redundancy, making it easy for an agent to parse quickly.

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

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

No output schema exists, so the description takes responsibility for explaining returns, which it does ('ranked list with score, confidence, signal density per entity'). It covers the process and use case well. Minor omissions like error behavior or rate limits are not critical given the read-only annotation and moderate complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add much beyond the schema, though it clarifies the role of entities (your brand vs competitors) which is already in the schema. The description adds no new parameter-specific 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 opens with a clear verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from the sibling tool ai_visibility_check by specifying multi-entity comparison and from generic compare_entities by focusing on AI visibility, ranking, and competitive audits.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example query. It implies this tool is for comparing multiple entities rather than probing a single one, but does not explicitly name alternatives or exclusions. Overall, the context is clear enough for an agent to select it appropriately.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations: composite fan-out, graceful partial failures, the 5-30s first-measurement latency on bundlephobia, and the sources_failed field indicating timeout behavior—none of which is visible from annotations alone.

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 value proposition, then usage guidance, return-format summary, ecosystem scope, and failure behavior—each sentence adds a distinct piece of information. No fluff or repetition of schema fields; despite its length, it's structurally tight.

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

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

For a tool with no output schema, the description compensates thoroughly by enumerating the returned summary fields (is_latest, license, bundle_kb_gz, etc.), advisory details, links, and recent versions. It also covers the critical edge cases of ecosystem limitations and timeout behavior, making it fully actionable for an agent.

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

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

Input schema covers 100% of parameters with descriptions, including the default behavior of 'version'. The description reinforces the scope ('npm package name') and mentions output fields, but it doesn't add new syntactic or semantic detail beyond the schema; therefore it sits at the 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 ('Composite ... check in ONE call') and explicitly describes the fan-out across deps.dev and bundlephobia. It distinguishes itself from siblings by naming its composite nature and NPM ecosystem scope, making its purpose unambiguous.

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

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

It provides explicit trigger phrasing: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also sets boundaries by stating NPM-only and directing PyPI/Maven/Cargo/Go to deps.dev:version directly, effectively covering when not to 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It adds the important nuance that this searches the global archive of experimentally-determined structures and returns PDB IDs for further use. This is useful context without contradicting annotations.

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

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

The description is compact and effective, starting with attention-grabbing example queries, then stating the core function and downstream use cases in a single sentence. Every piece of text earns its place, with no fluff.

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

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

Given the presence of a detailed input schema, an output schema, and comprehensive annotations (readOnly, idempotent, openWorld), the description covers the essential context: what it searches, what it returns, and how the results relate to sibling tools. There are no obvious gaps for this moderate-complexity tool.

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

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

The input schema provides 100% coverage for all three parameters (query, limit, return_type) with descriptions, so the baseline is 3. The description does not add much parameter-specific detail beyond the examples, which are also present in the schema. The examples in the description mirror the schema examples, so value added is minimal.

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 text search over the RCSB PDB archive, with specific example queries. It also distinguishes itself from sibling tools by mentioning that returned PDB IDs can be passed to `structure` or `summary`, establishing its role as a search front-end.

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 concrete example use cases (e.g., 'Find protein structure of [target]') and specifies the domain (structural biology, drug design, protein characterization). It implies integration with downstream tools but does not explicitly list when-not-to-use conditions, so it stops short of full exclusion guidance.

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

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

Goes beyond the annotations (readOnlyHint, etc.) by disclosing the output format (top-N passages with character offsets and similarity scores), the embedding model (BGE-base-en with cosine over 500-char overlapping windows), and the 200K char cap with truncation behavior. This is rich behavioral context not present in 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: purpose, use case, pairing, technical mechanics, and limitations. The description is front-loaded with the core action and stays focused without redundancy.

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

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

Covers what the tool does, when to use it, what it returns, how it works under the hood, and its limits. The absence of an output schema is compensated by the explicit description of return values. No gaps remain for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue') and framing 'text' as something already fetched (e.g., SEC 10-K body), which enriches the raw schema definitions.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which clearly identifies the tool's specific action and resource. It distinguishes itself from sibling tools like search by emphasizing operating on already-pulled text, and mentions saving context versus cramming the whole record into the prompt.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names a complementary tool (ask_pipeworx_grounded) and suggests a workflow, giving clear context for when this tool is preferable.

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

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

Annotations (readOnlyHint, idempotentHint) already communicate safety, so the description's burden is lower. The description adds value by specifying the output fields (experimental method, resolution, authors, deposition date, organism, ligands, related entities), which is useful context not present in 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 begins with three redundant quoted variants ('"PDB entry [1abc] details" / "fetch protein structure [pdb_id]" / "metadata for [PDB ID]"'), which adds noise and length without new information. The core sentence is concise and front-loaded, but the redundancy hurts structure.

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-parameter tool with an output schema, the description provides sufficient context: what it does, what it returns, and when to use it. It does not need to explain return values since an output schema exists, and the usage guidance makes it complete for the given complexity.

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

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

The schema has no description for pdb_id, and the description provides examples (1abc, 7BV2) plus the label 'PDB ID.' This gives basic semantics but does not explain format constraints, case sensitivity, or potential error cases. With 0% schema coverage, the description partially compensates but is not exhaustive.

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

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

The description clearly states the tool fetches a full PDB entry record by ID, listing specific return fields (method, resolution, authors, deposition date, organism, ligands, related entities). It distinguishes from sibling tools like search by providing a specific resource and verb, and the examples (1abc, 7BV2) clarify the input format.

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

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

It explicitly instructs to use this tool after `search` to inspect a specific structure, providing clear context for when to invoke it. This guidance implies it is not for discovery (use search instead), satisfying the explicit when/alternative criterion.

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

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

Beyond annotations, the description discloses enforcement details: phone verification requirement, 10/day SMS cap, webhook HMAC signing, one-time signing secret return, and auto-disable after 10 consecutive failures. The idempotentHint annotation is not explained in the text, but the description adds substantial behavioral context without contradicting annotations.

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

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

The description is dense but information-rich, with every clause serving a purpose. It front-loads the purpose and returns value, then details types and delivery. It is a long single paragraph and could benefit from bullets, but it contains minimal fluff and is well-organized internally.

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 three params (one nested), no output schema, and meaningful side effects, the description covers essential invoking context: return value, auth requirement, type-specific filters, delivery options, verification constraints, and webhook security behavior. It could mention duplicate/subscription idempotency behavior, but the annotation hints at it.

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

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

Schema description coverage is 100%, and the description's param examples (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) mirror the schema's own param descriptions. The only additional semantic is the return of a subscription id, which is behavioral rather than parameter-related.

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 'Create a proactive monitoring subscription to a live-data event stream,' providing a specific verb, resource, and scope. It clearly distinguishes subscribe from sibling tools like list_subscriptions and unsubscribe, and enumerates supported subscription types with concrete examples.

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

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

The description gives clear usage context: it requires an OAuth account, explains that anonymous/BYO cannot persist subscriptions, and mentions pulling fired alerts via recent_alerts or the registry URL. It does not explicitly contrast with list_subscriptions or unsubscribe, but the prerequisites and delivery-channel guidance are strong enough for correct invocation.

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 and idempotent hints, but the description adds valuable behavioral context: it explains what is returned (category-bucketed example questions with tool+argument shapes), how it behaves with no arguments vs. a topic, and that results are drawn from a live catalog. No contradiction with annotations.

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

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

Although the description is long, every sentence adds value: it front-loads the purpose with multiple phrasings, lists the return structure, shows call options, and gives direct usage guidance. No wasted words; the length is justified by the tool's onboarding role.

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, which it does explicitly. It also covers call patterns, topic parameter behavior, and when to use the tool. Given the tool's complexity and the absence of an output schema, the description is complete enough for correct selection and 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 coverage is 100% and the schema already describes the topic parameter. The description goes beyond by providing concrete examples ('finance', 'pharma', 'betting') and clarifying that omitting it gives a cross-category spread, which adds practical meaning to the 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 clearly states the tool is an onboarding entry point that returns category-bucketed example questions mapped to exact tools and argument shapes. It uses a specific verb ('suggest') and resource ('questions for Pipeworx'), and distinguishes itself from sibling tools like discover_tools and ask_pipeworx by emphasizing it's for learning what to ask.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. This provides clear when-to-use context, and the mention of alternatives (meta-tools) plus the distinction from discovery tools gives strong usage guidance.

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

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

The description adds behavioral details beyond the annotations by disclosing the endpoint fallback strategy ('tries the RCSB UniProt endpoint first, falls back to the core entry record') and enumerating the returned fields. The annotations already establish read-only, idempotent, and non-destructive behavior, so the additional context about the lookup mechanism is valuable and non-redundant.

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

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

The description is two sentences, front-loaded with the primary purpose ('Lightweight lookup for a PDB entry by 4-char ID'), and every clause adds essential information: endpoint behavior, return fields, and relationship to `structure`. There is 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 simple single-parameter read-only tool with an output schema, the description is complete. It covers what the tool does, how it works (endpoint fallback), what it returns, and how it relates to a sibling tool, without needing to explain return values because the output schema exists.

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

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

The schema has 0% description coverage, and the description compensates by specifying the valid format ('4-char ID') and the lookup behavior associated with the `pdb_id` parameter. It gives enough semantic context for an agent to understand what value to provide, though it does not mention validation rules beyond the character count.

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 ('lookup') and resource ('PDB entry by 4-char ID'), and explicitly distinguishes itself from the sibling `structure` by stating it returns metadata 'without the full polymer/ligand detail of `structure`.' This makes the tool's purpose unambiguous and differentiated.

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

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

The description clearly implies when to use this tool ('Lightweight lookup') and contrasts it with `structure` ('without the full polymer/ligand detail of `structure`'), giving the agent a clear choice based on need for detail. It does not explicitly state 'when not to use' or name alternative tools beyond `structure`, but the context provides sufficient 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?

It adds important behavioral details beyond annotations: ownership enforcement and the deactivation (not deletion) behavior, ensuring the user knows historical events remain available. This complements the idempotentHint and destructiveHint annotations.

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

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

The description is two concise sentences, front-loaded with the primary action, and every sentence provides useful context without redundancy.

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

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

For a simple tool with one parameter and no output schema, the description explains the primary action, the ownership constraint, and the deactivation behavior. This is complete for an agent to invoke correctly.

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

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

The input schema covers the sole parameter (id) fully, including its type and origin ('returned by subscribe'). The description does not add additional parameter semantics beyond 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 action: 'Cancel a subscription by id.' It specifies the resource (subscription) and the operation (cancel), and distinguishes itself from related tools like subscribe and list_subscriptions.

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

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

The description provides a clear usage context: you can only cancel your own subscriptions, which implies this tool is for the subscription owner. It doesn't explicitly mention alternatives, but the context is sufficient.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds significant context beyond this: the dual-path routing, tolerance_pct interpretation, verdict types, citation behavior, and the claim that it replaces 4–6 sequential calls. This provides useful behavioral transparency.

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

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

The description is a single dense paragraph that front-loads trigger phrases and purpose, then flows into routing and output details. Every sentence contributes value, though the length is slightly long. It is well-structured for the tool's complexity.

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

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

With no output schema, the description explains the return value (verdict, actual value with citation, reasoning). It also covers routing, tolerance behavior, and the efficiency benefit. This is complete for a tool with moderate complexity, though it could mention edge cases or limitations.

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 extra meaning for tolerance_pct, explaining how to override it for hallucination detection and that the default is implied by wording (capped at 5). The claim parameter already has good examples in the schema.

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

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

The description clearly states the tool's purpose as natural-language claim verification against authoritative sources, with explicit trigger phrases and examples. It distinguishes itself from siblings by focusing on fact-checking rather than search or research.

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 an explicit usage condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic (SEC EDGAR fast path vs. grounded pipeline) for different claim types. However, it does not explicitly name alternative tools or specify exclusions.

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