Spdx License

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

The description reveals the tool routes to 1,423+ tools and returns structured answers with stable pipeworx:// citation URIs. Annotations already indicate read-only; no contradiction. It adds useful behavioral context beyond annotations.

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

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

The description is somewhat verbose, listing many domains and examples. While well-structured, it could be more concise without losing clarity. Slightly longer than necessary for a simple single-input tool.

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

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

Given the tool's complexity as a meta-routing tool and lack of output schema, the description adequately explains what happens (structured answer with citations). It doesn't cover failure modes but is fairly complete for typical use.

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 'question' parameter, with a basic natural language hint. The description adds context about question types but no parameter-level details 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 using authoritative structured data with citations, and explicitly distinguishes itself from web search. The verb 'ask' and examples like 'current US unemployment rate' solidify the purpose.

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?

Excellent guidance: 'PREFER OVER WEB SEARCH', explicit list of use cases (SEC filings, FDA data, etc.), and concrete trigger phrases ('what is', 'look up', 'find'). It tells the agent exactly when 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?

Annotations indicate read-only; description adds data sources (SEC EDGAR, FAERS) and output format (paired data + citation URIs). No contradictions, and it provides useful behavioral context beyond annotations.

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

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

Compact yet comprehensive; front-loads purpose with examples, then details per type and return format. No wasted words.

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

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

Without output schema, description fully describes returns (paired data, URIs) and covers both entity types thoroughly. No gaps given tool complexity.

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

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

Schema coverage is 100%, but description enriches both parameters: explains 'company' vs 'drug' specific metrics, gives examples for 'values' (tickers, drug names), and clarifies min/max. Adds significant meaning.

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

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

The description clearly states the tool compares 2–5 companies or drugs side by side, with specific user prompt examples ('compare X and Y', 'X vs Y', etc.) and explicitly distinguishes from siblings by noting it replaces multiple sequential 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?

It provides explicit when-to-use scenarios (user wants comparisons, rankings) and implicitly excludes single-entity queries (handled by 'entity_profile'). It could mention alternatives like 'search' for broader queries, but the context is clear.

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

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

Annotations already declare readOnlyHint=true. The description adds the output format ('Returns the top-N most relevant tools with names + descriptions'), which is useful behavioral context beyond safety.

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 paragraph front-loaded with purpose. The list of domains is lengthy but functional. Could be slightly more concise, but it's well-structured and efficient.

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

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

Given no output schema, the description adequately explains the return format. It covers the essential context for a tool-discovery tool, though it omits pagination or result metadata, which is acceptable.

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

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

Schema coverage is 100%, so baseline is 3. The description only implicitly references the 'limit' parameter via 'top-N'. It doesn't add new details beyond the schema, which already describes both parameters well.

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

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

The description clearly states it's for discovering tools by describing a data or task, listing specific domains. It distinguishes itself from siblings like 'search' by emphasizing it's a meta-tool for tool selection, not data querying.

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 tells when to use ('browse, search, look up') and advises to 'Call this FIRST' when needing to see options, implying alternatives. This provides clear context without being verbose.

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 declare readOnlyHint=true, consistent with the tool's read-only nature. The description adds behavioral details (returns filings, fundamentals, patents, news, LEI with citation URIs) and notes the current type limitation. However, it does not disclose potential rate limits or result structure.

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 paragraph that front-loads the main purpose, then provides usage patterns, and lists contents. It is informative and concise with no wasted words.

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

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

Given no output schema, the description reasonably explains return categories (SEC filings, fundamentals, patents, news, LEI) and mentions citation URIs. However, it lacks details on result format or pagination, which could be helpful.

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 clarifying that 'type' only supports 'company' and explaining that 'value' accepts ticker or zero-padded CIK, explicitly stating that names are not supported, which goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Get everything about a company in one call.' It provides concrete use case examples like 'tell me about X' or 'research Microsoft' and lists specific data sources (SEC filings, fundamentals, patents, news, LEI), distinguishing it from separate pack tools.

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

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

The description explicitly states when to use: when a user asks for company info, and when not to use: if only a name is available, it advises using resolve_entity first. This provides clear context and 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 explicitly says 'Delete', which is consistent with the readOnlyHint=false annotation, and it adds context about clearing sensitive data, but does not disclose additional behavioral details beyond the 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?

The description is two sentences, front-loaded with the core functionality, and every sentence adds value without unnecessary fluff.

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

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

For a simple delete tool with one parameter and no output schema, the description covers purpose, usage context, and sibling relationships fully, leaving no gaps.

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

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

The schema already fully describes the parameter 'key' as 'Memory key to delete' with 100% coverage, so the description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and it distinguishes itself from siblings remember and recall.

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 provides when to use the tool: when context is stale, task is done, or to clear sensitive data, and it pairs with remember and recall, offering clear guidance on 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 show readOnlyHint=true, consistent with a read operation. The description mentions 'metadata + descriptors' but does not detail the output structure; given no output schema, more disclosure would help.

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 one sentence, concise, and front-loaded with the key action, containing no extraneous words.

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

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

For a simple retrieval tool with one parameter and no output schema, the description covers essential purpose and input. It misses return format details but is adequate given sibling tools.

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 sole parameter 'id' is described with examples ('MIT', 'Apache-2.0'), compensating for the schema's 0% description coverage.

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

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

The description clearly states 'Get metadata + descriptors for one SPDX license id' with explicit examples, and it distinguishes from sibling tools like 'list_licenses' and 'get_license_text'.

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

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

It specifies when to use (for a specific SPDX license ID) and implies alternatives via sibling names, 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?

Annotations already provide 'readOnlyHint: true', indicating a safe read operation. The description adds that the tool returns standard text and cross-references, which is helpful but does not disclose additional behavioral traits like error handling or data sources. It does not contradict 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 a single, clear sentence of 15 words that front-loads the verb and resource. Every part is necessary and there is no wasted text.

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

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

Given the tool's simplicity (one parameter, read-only, no output schema), the description adequately explains the return value (standard text and cross-references). It does not cover edge cases like invalid IDs, but for a straightforward retrieval tool this is acceptable.

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?

With 0% schema coverage for the single required parameter 'id', the description compensates by explaining it is a 'single SPDX license id'. This adds critical meaning beyond the raw schema, though it does not specify format or constraints (e.g., valid SPDX format).

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 verb 'Get', the resource 'full license text for a single SPDX license id', and specifies the return includes 'standard text + cross-references'. It differentiates from siblings like 'list_licenses' or 'get_license' by focusing on full text retrieval for a specific ID.

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

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

The description implicitly tells when to use (when you have a single SPDX license id and need the full text), but does not explicitly exclude scenarios or mention alternatives. The context is clear but lacks explicit when-not 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. The description adds filter options but lacks behavioral details like pagination, default behavior without filters, or filter combination logic.

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 wasted words.

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

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

Missing details like default values, filter combination logic, and return format. Given no output schema, description could be more helpful about what the tool returns.

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

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

The description adds meaning to two boolean parameters (osiApproved, fsfLibre) beyond the schema, which only describes deprecated. However, it does not specify default values for all parameters.

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 'List SPDX licenses' with optional filters, using a specific verb and resource. It distinguishes from siblings like get_license and get_license_text, which handle single license retrieval.

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 for listing with filters, but does not explicitly specify when to use this tool versus alternatives, nor mention exclusions or prerequisites.

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 rate limits (5 per identifier per day), cost (free, no quota impact), and processing (team reads daily, influences roadmap). No annotations contradict; readOnlyHint=false is consistent with writing feedback.

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?

Five concise sentences that front-load purpose, then guide usage, then provide restrictions. No redundancy or unnecessary 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 the tool's simplicity (3 params, no output schema), the description covers purpose, use cases, content guidelines, and limitations completely. No missing information for effective use.

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

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

Schema coverage is 100%, so parameters are well-defined. The description adds valuable usage guidance for the 'type' (e.g., explaining enum options) and 'message' (specificity encouragement). This enhances 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 clearly states the tool's purpose: to provide feedback to the Pipeworx team about bugs, features, data gaps, or praise. It is specific and distinct from sibling tools, which serve different purposes like searching or comparing 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?

Explicitly lists when to use (bug, feature, data_gap, praise) and provides content guidelines (describe in terms of tools/packs, don't paste user prompt). Lacks explicit exclusion of when not to use, but context makes it clear this is for feedback only.

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 behavioral traits beyond the readOnly annotation, such as scoping to the user's identifier and the behavior when omitting the key (list all). 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 three sentences, front-loading the primary action and then providing usage context. Every sentence is informative and there is no wasted text.

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

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

The description is complete for the tool's simplicity, covering purpose, usage, and behavior. However, it lacks details about return format or error handling (e.g., when key not found), which would be helpful given no 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?

The input schema covers 100% of parameters with descriptions. The description adds context about parameter usage (omit to list all) and pairs with remember/forget. It does not add new parameter-level details beyond the schema, but the clarification is valuable.

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: retrieve a saved value or list all saved keys. It uses specific verbs (retrieve, list) and resources (previously saved context). It distinguishes from sibling tools by mentioning 'remember' and 'forget' in the description.

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 when to use the tool: to look up context stored earlier without re-deriving it. It also implies when not to use by contrasting with 'remember' and 'forget'. The sibling context provides clear 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 include readOnlyHint=true, and the description adds behavioral details: fans out to SEC EDGAR, GDELT, USPTO, returns structured changes, total_changes count, and 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 concise, well-structured, and front-loaded. Two sentences plus examples convey the purpose, usage, and behavior without unnecessary words.

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

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

Given 3 parameters, no output schema, and the tool's complexity (parallel fan-out), the description provides enough context: what it returns (structured changes, count, URIs) and how to specify parameters. Could mention limits or error handling, but adequate for typical use.

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 meaningful context: since parameter format (ISO or relative) with examples, value as ticker or CIK, and type as only 'company'. It does not repeat schema verbatim but complements it.

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: retrieving recent changes for a company. It provides a specific verb ('What's new') and resource ('a company'), and the use case examples distinguish it from siblings like entity_profile or 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 explicitly specifies when to use this tool with example queries, and mentions it fans out to multiple sources. It does not explicitly state when not to use it, but the context is clear enough for an AI agent.

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

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

Annotations provide readOnlyHint=false, and the description adds key behavioral details: key-value storage, scoping by identifier, and persistence duration (24 hours for anonymous, persistent for authenticated). 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 a single paragraph with front-loaded purpose. Each sentence adds value (usage, pairing, scope, retention). Slightly long but efficient for the information conveyed.

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 simple tool (2 required params, no output schema, 2 siblings), the description covers all necessary context: purpose, usage, pairing, scope, retention. No gaps identified.

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 key and value. The description reinforces with examples and clarifies the purpose of each parameter, adding meaning 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 saves data for later reuse across conversations or sessions, with specific examples (resolved ticker, target address, user preference, research subject). It distinguishes from siblings like recall and forget, achieving a specific verb+resource with differentiation.

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 when to use ('when you discover something worth carrying forward'), when not to use by implication (if data isn't worth reusing), and explicitly pairs with recall and forget. Includes context on authenticated vs. anonymous session retention.

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 that the tool is read-only ('readOnlyHint: true' annotation) and adds context about the output: it returns IDs plus 'pipeworx:// citation URIs.' It lists the ID systems it covers and provides examples. This goes beyond the annotations by specifying return format and citing specific ID types, making behavior 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?

The description is four sentences, front-loaded with the main purpose and use case. It includes examples and additional value (citation URIs) without redundancy. While not extremely terse, it earns its length with useful 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 the tool's complexity (two parameters, no output schema, read-only), the description covers the essential: what IDs it returns, when to call it, and the output format (including pipeworx URIs). It could mention pagination or limits (if any), but for a simple lookup tool, it is sufficiently complete.

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

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

With 100% schema description coverage, the description still adds significant value. It provides concrete examples ('Apple' → AAPL / CIK, 'Ozempic' → RxCUI) and explains the types of IDs returned. This enriches the parameter semantics beyond the schema's enum and string descriptions.

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

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

The description clearly states the tool's purpose: 'Look up the canonical/official identifier for a company or drug.' It specifies the verb (look up), resource (identifiers), and scope (company or drug), and provides examples. This distinguishes it from siblings like entity_profile (which likely provides broader data) and 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 explicitly advises using this tool 'BEFORE calling other tools that need official identifiers' and notes that it 'Replaces 2–3 lookup calls.' It gives context for when to use it (when a user mentions a name and you need CIK, ticker, RxCUI, or LEI). It lacks explicit exclusions or alternatives, but the guidance is clear and actionable.

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 value by specifying case-insensitive substring matching. However, it does not disclose what the return format is (e.g., list of licenses) or any limits (pagination, result count). The description adds some behavioral context beyond annotations but is incomplete.

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, tight sentence with no extraneous information. It front-loads the action and scope, making it highly 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?

For a simple search tool with a single parameter and read-only annotation, the description covers the search mechanism but omits return type or behavior. Without an output schema, the agent lacks information on what the response contains (e.g., list of objects). Moderate completeness.

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% for the single 'query' parameter. The description effectively explains the parameter's purpose: a substring to search across SPDX ID and full license name, case-insensitive. This compensates well for the lack of schema documentation.

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

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

The description clearly states it performs substring search across SPDX ID and full license name, case-insensitive. The verb 'substring search' and the specific resources distinguish it from sibling tools like 'list_licenses' (list all) and 'get_license' (exact match).

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

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

No guidance is provided on when to use this tool versus siblings. It does not mention alternatives like 'list_licenses' for full lists or 'get_license' for exact matches, nor does it specify prerequisites or context.

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

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

Given the readOnlyHint annotation (which already signals safety), the description adds behavioral context by detailing the return value (verdict, structured form, actual value with citation, percent delta) and efficiency benefit (replaces 4-6 sequential calls). 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?

At 5-6 sentences, the description is compact. The first sentence clearly captures the essence, followed by usage triggers, scope, and output summary. No superfluous 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 the tool's simplicity (one required parameter, no output schema, no nested objects) and rich schema/annotations, the description completely covers purpose, usage context, input format, output details, and scope limitations. No 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 covers 100% of the single parameter with a description. The tool description enriches this by providing two concrete examples of valid claim formats ('Apple's FY2024 revenue...') and clarifies that the claim is a natural-language statement, adding meaning beyond the schema's brief description.

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 'Fact-check, verify, validate, or confirm/refute' and identifies the resource 'natural-language factual claim' against 'authoritative sources'. It distinguishes itself from sibling tools by specifying its domain (company-financial claims via SEC EDGAR+XBRL), clearly differentiating from search, compare, and profile tools.

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

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

The description explicitly states when to use the tool ('when an agent needs to check whether something a user said is true') and provides example question patterns. It also defines the scope limitation ('v1 supports company-financial claims'), which implicitly guides when not to use. However, it does not explicitly mention alternative tools for out-of-scope claims.

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