Schemastore

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

Annotations indicate readOnlyHint=true, matching the description's implication of data retrieval. Description adds context: routes to 1,423+ tools, fills arguments, returns structured answer with stable citation URIs. 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?

Front-loaded with key directive. Includes examples and clarifications. While slightly long, every sentence adds value. Efficient for the complexity explained.

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 massive scope (1,423+ tools, 392 sources), the description sets clear expectations: answers have citations, questions should be factual. No output schema, but description mentions structured answer format. Very complete for decision-making.

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?

Single parameter 'question' with a basic schema description. The tool description significantly enriches this by specifying the types of questions (factual, real-world, entities) and providing examples, compensating for the schema's lack of detail.

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 the tool routes questions to a vast array of authoritative structured data sources with citations. It distinguishes itself from web search by emphasizing structured, cited answers for factual queries about real-world entities, events, and numbers.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and lists specific domains (SEC filings, FDA data, etc.) and query types ('what is', 'look up', 'find', etc.). Provides concrete examples, telling both when and why to use this tool over alternatives.

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

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

The description discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), that it's read-only (consistent with readOnlyHint=true), return format (paired data + URIs), and performance benefit (replaces multiple calls). Adds value 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 5 sentences, well-structured with purpose first, then usage, then details. No redundant information.

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

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

Given no output schema, the description adequately explains return values (paired data, citation URIs). Covers inputs, types, examples, and output. Complete for a comparison 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%. The description adds meaning by explaining what each type pulls (revenue/debt for company, adverse events/approvals/trials for drug) and provides concrete examples beyond schema documentation.

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

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

The description clearly states the tool compares 2-5 companies or drugs side by side, with specific verbs and resources. It distinguishes from siblings by noting it replaces 8-15 sequential agent calls.

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 scenarios (e.g., 'compare X and Y', 'which is bigger') and provides examples for both entity types. It lacks explicit 'when not to use' but context is clear.

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

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

The description aligns with the readOnlyHint annotation, indicating no destructive side effects. It adds that the tool returns 'top-N most relevant tools with names + descriptions'. 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 moderately concise, front-loading the purpose and listing common use cases. It could be slightly shortened but remains informative 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 discovery tool with only two parameters and no output schema, the description provides sufficient context: what it does, when to use it, what it returns, and the domains it covers. It lacks explicit output format but 'names+descriptions' is clear enough.

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

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

The schema already describes both parameters (query and limit) with 100% coverage. The description adds no further parameter details beyond confirming that limit controls 'top-N' count, which matches the schema. 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 finds relevant tools based on a description, with a specific verb ('find', 'discover') and resource ('tools'). It distinguishes itself from sibling tools by focusing on browsing and discovering which tool to use, not executing a specific task.

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 advises 'Call this FIRST when you have many tools available'. It provides clear context but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, and the description adds context about what data is returned: recent SEC filings, financials, patents, news, and LEI with citation URIs. 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 two sentences: the first clearly states purpose and use cases, the second details return data. Every sentence adds value, and it is front-loaded with the core purpose.

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 covers all key return elements in sufficient detail (filings, financials, patents, news, LEI). The tool is complex but the description is complete for the agent to understand what to expect.

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

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

Schema coverage is 100%, but the description adds value by explaining the 'type' parameter can only be 'company' and that 'value' accepts a ticker or zero-padded CIK. It also clarifies that names are not supported and points to 'resolve_entity' for name resolution.

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

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

The description starts with 'Get everything about a company in one call', clearly stating the purpose. It provides specific example queries and distinguishes itself from sibling tools like 'resolve_entity' by explicitly stating that names are not supported and that one should use 'resolve_entity' first if they have a name.

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 when to use this tool (when a user asks for a company profile) and provides specific query examples. It also tells when not to use it (if only a name is available) and directs to an alternative tool ('resolve_entity').

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, so no contradiction. The description adds the host constraint, but does not disclose error behavior (e.g., URL not on allowed host) or if additional network access occurs. Adequate but could be more transparent.

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

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

Single sentence, no unnecessary words. Well-structured with the constraint placed naturally.

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 fetch tool with one parameter and a clear return type (JSON Schema document), the description provides sufficient information. No output schema is needed as the return document is self-descriptive.

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 for the single parameter, including a description and example. The description adds the host constraint, which complements the schema. No further detail needed.

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 ('Fetch'), resource ('JSON Schema document'), and constraint (URL must be on json.schemastore.org). It clearly distinguishes from siblings like 'list_schemas' (list all) and 'find_schema_for' (search).

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

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

The description implies usage when you have a specific URL to a JSON Schema on the allowed host, but does not explicitly mention when not to use it or suggest alternatives. Minimal 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 indicate readOnlyHint=true, so the description adds no new behavioral details beyond a consistent read operation. No mention of performance, matching behavior, or edge cases. With annotations handling safety, a 3 is appropriate.

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?

Single sentence, front-loaded with purpose, no unnecessary words. Every word earns its place.

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

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

With one parameter, no output schema, and read-only annotation, the description is sufficient. It tells what the tool does and how the parameter is used. Could be improved by hinting at the return format, but not essential given simplicity.

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

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

Schema coverage is 100%, but the description adds context about 'fileMatch globs', which clarifies how the filename parameter is used (matching against glob patterns). This adds meaning beyond the schema's example value.

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

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

Description clearly states the action: 'Find catalog entries whose fileMatch globs cover the given filename.' It uses a specific verb ('Find') and resource ('catalog entries'), and distinguishes from sibling tools like 'list_schemas' (which likely lists all) and 'fetch_schema' (which retrieves a specific schema).

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?

Description implies the tool is used when you have a filename and want matching schemas, but does not explicitly state when to use it versus alternatives (e.g., 'list_schemas') or provide exclusions. Context is clear but guidance is minimal.

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 indicate mutation (readOnlyHint=false). Description consistently says 'delete' and explains the effect (removes stored memory). No contradictions, adequate behavioral disclosure.

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 that are direct and front-loaded. Every word adds value; no filler.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description covers purpose, usage context, and relationship to siblings. Complete for an agent to correctly select and invoke 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?

Schema coverage is 100%, and the schema already describes 'key' as 'Memory key to delete'. Description adds no extra meaning beyond this, so baseline score of 3 applies.

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

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

Description clearly states the tool deletes a memory by key, with a specific verb and resource. It distinguishes from siblings 'remember' and 'recall' as the deletion counterpart.

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 contexts for use (stale context, task done, clear sensitive data) and mentions pairing with related tools. Doesn't include when not to use or alternatives, but context is clear.

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

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

Annotations provide readOnlyHint, so safety is clear. Description adds case-insensitive filter behavior and specific filter fields, which is helpful 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?

Single sentence, front-loaded purpose, no extraneous words. Earns its place efficiently.

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 simple tool with 2 optional params, no output schema, description covers purpose and filter behavior completely.

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%, baseline 3. Description adds that the filter applies to specific fields (name, description, fileMatch) and is case-insensitive, adding value beyond schema.

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

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

Description clearly states 'List SchemaStore catalog entries' with specific verb and resource. Differentiates from siblings like fetch_schema or find_schema_for which are more specific.

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

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

Clear implication of usage for listing schemas with optional filter. No explicit when-not-to-use but siblings provide implicit 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 mark it as read-only. The description adds case-insensitivity, which is useful. However, it does not mention behavior on missing names or return format, leaving some gaps.

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?

A single, clear sentence with no wasted words. All information is front-loaded and directly relevant.

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 lookup tool with one parameter and no output schema, the description is decent but incomplete. It does not specify what the tool returns (e.g., entity details, boolean existence), which may confuse an AI agent.

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

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

The schema covers the parameter with an example. The description adds semantic context ('exact-name', 'case-insensitive') that clarifies how the name parameter is interpreted, going 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 it performs an exact-name lookup against the catalog, with case-insensitivity. However, it does not differentiate from sibling tools like 'discover_tools' or 'entity_profile', which also look up entities.

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

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

No guidance on when to use this tool versus alternatives. It implies use for exact name matching but does not specify when not to use it or provide comparisons.

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

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

Beyond the annotation (readOnlyHint: false), the description details important behaviors: rate-limited to 5 per identifier per day, free usage not counting against quota, and that the team reads digests daily with direct roadmap impact. This gives the agent full understanding of implications.

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 at about 100 words, with clear structure: purpose, usage guidelines, limitations. Every sentence adds essential information, making it efficient for an agent to parse.

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 adequately covers return expectations (none needed). It addresses all necessary context: when to use, how to format, rate limits, and impact. The simplicity of the tool means no further details are 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?

Schema coverage is 100%, and the description adds significant meaning by expanding on the enum values (e.g., explaining when to use 'bug' vs 'feature') and providing context for the message field (be specific, 1-2 sentences, 2000 chars max). This aids correct parameter usage beyond the 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 clearly states the tool's purpose: to tell the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs (tell, describe) and explicitly lists the types of feedback, distinguishing it from other tools on the server which are for data retrieval or analysis.

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 for each feedback type (bug, feature, data_gap, praise) and includes what not to do ('don't paste the end-user's prompt'). It also mentions rate limits and that it's free, helping the agent decide when to invoke this tool without concern for cost.

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 readOnlyHint: true, consistent with retrieval. Description adds context: scoped to identifier, listing behavior when key omitted, and relationship to remember/forget. 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?

Three sentences, front-loaded with action and resource, no wasted words. Every sentence provides value.

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

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

For a one-optional-param tool with readOnlyHint annotation and no output schema, the description covers behavior, scope, and sibling relationships completely.

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 description for key parameter. Description adds value by explaining omission lists all keys, scoping, and pairing with other tools, exceeding baseline for full coverage.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if omitted. It identifies the resource (saved values) and action (retrieve/list), distinguishing it from sibling tools remember and forget.

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

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

The description explains when to use: to look up context stored earlier without re-deriving. It mentions scoping to an identifier and pairing with remember/forget, but lacks explicit 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?

The description adds behavioral context beyond the readOnlyHint annotation: it explains that the tool fans out to SEC EDGAR, GDELT, and USPTO in parallel, and describes the return format (structured changes, count, citation URIs). This provides useful transparency about the tool's actions and output.

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 (around 4 sentences) and front-loaded with the main purpose. It wastes no space, but could be slightly more structured (e.g., bullet points) to improve readability. However, it is efficient and clear.

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

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

Given the absence of an output schema, the description adequately explains the return type (structured changes, count, URI citations). It covers the key aspects: purpose, when to use, parameters, and behavior. The tool is relatively simple, so this level of detail is sufficient.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by clarifying the 'since' parameter with examples (ISO date or relative shorthand) and typical use ('30d' for monitoring), and by explaining that 'value' can be a ticker or CIK. These details help the agent use 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 as retrieving recent changes about a company, with specific user query examples. It mentions fanning out to multiple data sources, which gives a clear scope. Although sibling differentiation could be more explicit, the purpose is very specific and distinguishable from other tools like entity_profile or compare_entities.

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 when' scenarios with concrete user queries and mentions monitoring. However, it does not specify when not to use this tool or suggest alternatives among sibling tools, which would improve guidance.

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

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

Discloses persistence behavior (24h for anonymous, persistent for authenticated) and scoping by identifier. Consistent with readOnlyHint=false annotation.

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 focused sentences: purpose, use case, behavioral details. No wasted words, front-loaded with key action.

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 all necessary information: what, when, how, pairing with siblings, and persistence. No output schema needed for a write-only tool.

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

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

Schema already provides good descriptions for key and value (100% coverage). Description adds examples and context (e.g., 'resolved ticker, target address') that enhance understanding beyond 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?

Clearly states 'Save data the agent will need to reuse later' and specifies key-value pair storage. Distinguishes from siblings recall and forget by mentioning pairing.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides examples of data types. Also instructs to pair with recall and forget for full lifecycle.

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 mark readOnlyHint: true, and description confirms it's a lookup. Adds behavioral details: returns IDs plus pipeworx:// citation URIs, and replaces multiple lookups.

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?

Four concise sentences, front-loaded with purpose, each adding value: usage guidance, examples, and summary. 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?

No output schema, but description explains return values (IDs and URIs) and usage context. Covers all necessary aspects for a two-parameter tool.

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

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

Schema description coverage is 100%, and description adds examples and clarifies the meaning of parameters (e.g., 'for company: ticker, CIK, or name'). Enhances but not essential given 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 specifies the action ('Look up'), the resource ('canonical/official identifier for a company or drug'), and distinguishes from siblings by stating it replaces 2-3 lookup calls and is a precursor to other tools.

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

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

Explicitly instructs to use 'BEFORE calling other tools that need official identifiers', and provides examples. Lacks explicit when-not-to-use alternatives, but context is strong.

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 details the return values: 'a verdict (confirmed / approximately_correct / refuted / inconclusive / unsupported), extracted structured form, actual value with pipeworx:// citation, and percent delta.' It also explains the underlying process, going beyond the readOnlyHint annotation. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the purpose. However, it includes some redundant phrasing (e.g., 'Fact-check, verify, validate, or confirm/refute') and technical details (e.g., 'v1 supports company-financial claims via SEC EDGAR + XBRL') that could be streamlined without losing clarity.

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 fully specifies all output fields (verdict types, structured form, actual value, citation, percent delta). It also mentions the domain scope and replaces multiple sequential calls, making it self-contained for an agent to understand inputs, outputs, and capabilities.

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 'claim' parameter is fully covered by the schema description (100% coverage). The tool description adds context about the format ('Natural-language factual claim') and gives concrete examples ('Apple's FY2024 revenue was $400 billion'), which aids understanding but is not strictly necessary given 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: 'Fact-check, verify, validate, or confirm/refute a natural-language factual claim or statement against authoritative sources.' It provides specific verbs, a concrete resource (authoritative sources), and gives examples like 'Is it true that…?' This distinguishes it well from sibling tools that handle other tasks like entity resolution or schema discovery.

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

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

The description explicitly tells when to use the tool: 'Use when an agent needs to check whether something a user said is true' with example phrasings. It also clarifies the current domain limitation (company-financial claims for US public companies via SEC EDGAR + XBRL), guiding agents on scope and preventing misuse.

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