Opencitations

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds behavioral context: it makes external API calls to Anthropic if an API key is provided, explains the payment model (BYO key, pay directly), and describes the return structure. 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, each earning its place. The first sentence states the core purpose, the second provides operational details (default model, API key), and the third lists use cases. 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 fully describes the return format (per-model score, confidence, signals, raw_response + combined view). It also clarifies entity scope and context parameter usage. The description compensates completely for the absence 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?

All 4 parameters have descriptions in the schema (100% coverage). The description adds value by providing examples for entity, specifying allowed model strings (workers-ai, anthropic), explaining _apiKey pass-through, and clarifying context purpose for disambiguation. This goes beyond the baseline of 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?

Description clearly states the tool probes LLMs for knowledge about a business/product/topic and returns a visibility score (0-100) per model. It specifies the verb 'probe', the resource 'LLMs', and the output format. It differentiates from siblings like scan_competitor_ai_presence and 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?

Description explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and optional Anthropic key usage, giving clear context for when to use the tool. However, it does not explicitly state when not to use it or name alternatives beyond the implicit sibling tools.

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

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

The description adds valuable behavioral context beyond the annotations: it routes questions to 3,745 tools, fills arguments, and returns structured answers with citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with a powerful usage directive and organized by examples. It is concise yet comprehensive, though slightly lengthy.

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 adequately explains the output format (structured answer with citation URIs) and covers the tool's purpose and usage. It is sufficiently complete for a query 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 aliases documented. The description adds natural language usage guidance and examples, enhancing the schema's 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 specifies the tool as a router to thousands of verified sources for factual queries, explicitly contrasting with web search and listing specific data types (SEC filings, FDA, economic stats, etc.). It clearly identifies the resource and action.

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 preference over web search and gives concrete usage cues ('what is', 'look up', 'find') along with examples. It does not explicitly state when not to use it, 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?

Description adds context beyond annotations: costs one extra LLM call, returns explicit refusals (not_in_source, no_tool_match, etc.), and uses only tool result data. Annotations already declare readOnlyHint, so no 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?

Description is concise but packs considerable detail; slightly long yet every sentence adds value. Could be more front-loaded but overall effective.

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 essential aspects: purpose, usage, return format (with fields), refusal reasons, and cost trade-off. No output schema exists, so description compensates fully.

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 has 6 parameters (all aliases for 'question') with 100% coverage. Description mentions natural language but adds little beyond 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?

Description states it is a hallucination-resistant answer mode for high-stakes reads, explicitly distinguishing from sibling 'ask_pipeworx' by specifying it extracts answers only from tool results and returns refusals when data insufficient.

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 advises use when answers will be quoted/cited/acted upon and must not invent facts, and recommends using 'ask_pipeworx' for casual lookups. Also lists refusal reasons indicating when not to rely on result.

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

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

The description extensively discloses behavioral traits beyond annotations: low-confidence resolutions short-circuit with status, closed markets return specific status, wide-spread markets carry tradeability notes, resolution-rule parsing, parent event extraction, news fallback behavior, etc. No contradictions with annotations (readOnlyHint, openWorldHint, etc.).

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 very long, covering many details in multiple paragraphs. While structured with section-like headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES), it could be more concise. Some redundancy exists (e.g., explaining resolution routes twice). It earns its length but is not maximally 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 the tool's complexity (classifiers, fan-outs, response shapes, safety checks), the description is complete. It covers inputs, behavior, edge cases, response structure, and error handling. Even without an output schema, it thoroughly describes what agents can 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%, and the description adds substantial meaning: for `market`, it explains input formats; for `depth`, it clarifies the enum values; for `include_raw`, it details the size implications and use cases ('keeps responses under ~20KB' vs '50KB-500KB'). This far exceeds baseline expectations.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and input formats (slug, URL, question text). While it does not explicitly differentiate from siblings, the specificity is high enough to distinguish.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It includes numerous examples (BTC bet, Fed bet, etc.) but does not mention when not to use it or suggest alternatives from the sibling list, slightly reducing clarity.

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, openWorldHint, idempotentHint, destructiveHint. Description adds no extra behavioral context beyond confirming the action.

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 concise sentences, front-loaded with action, 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 low complexity (single parameter, output schema exists), description is complete: explains what it does and when to use 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?

Description explains the parameter 'oci' as 'Open Citation Identifier', adding meaning beyond the schema which only defines type string. With 0% schema coverage, description compensates 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 the tool fetches a single citation record by OCI, and distinguishes it from sibling tools like citations, references, and metadata by calling it a specialist tool.

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 'most users want `citations` / `references` / `metadata` instead', providing when to use and when not, and naming 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 readOnlyHint, openWorldHint, idempotentHint. The description adds that it's a 'fast version', but no further behavioral details are provided. This is adequate given the rich 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, front-loaded with common query patterns, and every sentence adds value. 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?

For a simple read-only tool with one parameter and an output schema, the description is sufficiently complete. Annotations cover safety, and the 'fast version' distinction adds practical context.

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%, but the description includes example queries showing the DOI format, which partially compensates. However, explicit description of the 'doi' parameter is missing. For a single obvious parameter, this is acceptable but not excellent.

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 returns citation count for a DOI, using specific verb and resource. It distinguishes itself from the sibling tool `citations` by noting it's a fast version when only the count is needed.

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

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

Explicitly says to use when only the count is needed, not the citing DOIs, referencing the `citations` alternative. However, it doesn't mention other alternatives like `references_count` or 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, openWorldHint, idempotentHint, and destructiveHint. The description adds useful use-case context but does not reveal additional behavioral traits beyond what annotations already provide.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and packs in multiple phrasings and use cases 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 the simple parameter, rich annotations, and presence of an output schema, the description covers the necessary context for an AI 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?

With 0% schema description coverage, the description must explain the parameter. It clearly identifies 'doi' as a DOI of a paper/study and provides examples in the schema, adding meaning beyond the schema definition.

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 provides a specific verb-resource pair ('who cites paper') and explicitly states it returns DOIs citing the given DOI, distinguishing it from similar tools like 'references' by stating it's the reverse direction.

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 phrase 'Use for impact analysis, follow-on research discovery, “is this paper influential” questions' gives clear context for when to use the tool, though it does not explicitly exclude other uses or mention 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, open-world, idempotent, non-destructive. Description adds context: pulls from SEC EDGAR/XBRL for companies (with off-calendar fiscal year handling) and FAERS for drugs, sorts by primary metric, returns citation URIs. No 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?

Description is detailed but each sentence serves a purpose. Front-loaded with example queries, then guidelines, then specifics. Could be slightly more concise, but effective.

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 usage, data sources, edge cases (off-calendar fiscal years), and return format hints (paired data, citation URIs). No output schema, but description sufficiently informs behavior. Minor gaps in exact output structure.

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 both parameters with descriptions. Description enriches by explaining data fields for each type (e.g., revenue, net income for companies) and provides examples. Adds value beyond 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 uses specific verbs like 'compare', 'side-by-side comparison', and provides example queries ('X vs Y', 'which is bigger'). It clearly states it compares 2–5 companies or drugs, distinguishing it from sequential single-pack lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides data source details for each type and specifies count limits. Gives clear when-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?

Discloses decomposition, parallel routing, evidence extraction with confidence, source, and citations. States expected response time (15-60s) and billing requirements for certain depths. Aligns with annotations (read-only, idempotent) 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 well-structured, starting with the main value proposition, then explaining the mechanism, providing usage examples, and ending with prerequisites. Each sentence contributes essential information 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?

Given the tool's complexity, the description covers all necessary aspects: what it does, how it works, what it returns (findings packet with evidence, citations, gaps), and context on speed and access requirements. No output schema exists, so the description adequately explains outputs.

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 'question' parameter accepts broad/multi-part input, and 'depth' options mean quick=3, standard=5, thorough=8 facets. Also notes the default for 'depth' and the paid plan requirement for 'thorough'.

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 by decomposing complex questions and parallelizing across numerous sources. It distinguishes itself from siblings like 'ask_pipeworx' by explicitly noting it is for broad or multi-part questions.

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 (broad, multi-part questions) and when not to (single lookups should use ask_pipeworx). Also mentions prerequisites: requires a Pipeworx account and a paid plan for 'thorough' depth.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, ensuring the agent knows it's safe. The description adds valuable behavioral context: returns top-N relevant tools with full schemas and curated examples, ready to call directly without a second lookup.

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 function, then lists use cases, and explains the output format concisely. Every sentence adds unique value, 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?

No output schema exists, but the description fully explains the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' Also mentions limit default/max. Complete for this discovery tool.

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

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

Schema coverage is 100% with detailed descriptions for each parameter (query, q, task, limit, etc.). The description does not add new parameter meaning beyond the schema but provides usage context via examples. 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 ('Find tools by describing the data or task.') clearly states the verb (find) and resource (tools), and provides extensive examples of data/task types (SEC filings, FDA drugs, etc.). It distinguishes itself from sibling tools like deep_research or validate_claim by being a discovery tool.

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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and implies it's for exploration before selecting specific tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds significant behavioral detail: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), mentions the USPTO API sunset and soft-fail behavior, and specifies input limitations (no names). 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 that effectively front-loads purpose and usage examples, then lists data elements. While slightly lengthy, every sentence provides value and no redundant information is present. The structure could be improved with bullet points, but it remains concise enough.

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

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

Despite lacking an output schema, the description fully explains return values: cik, company_name, recent_filings (with URIs), fundamentals (with fields and sorting), patents (with fallback note), news, and LEI. It also mentions the parallel execution and input constraints. For a multi-source tool, this is comprehensive.

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 descriptive parameter definitions. The description adds minor nuance (e.g., 'Only company supported, person/place coming soon' for type, and reiterates ticker/CIK format for value). This adds marginal value beyond the schema, meeting the baseline expectation for high 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 uses specific verbs like 'profile' and resource 'entity' for US public companies. It clearly distinguishes from chaining single-source lookups by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and lists the exact data returned (cik, filings, fundamentals, patents, news, LEI). Examples of user intents are provided.

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

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

Explicit guidance is given on when to use: when user asks for a holistic view of a US public company, and to prefer this over chaining. It also clarifies that names are not supported, advising to use resolve_entity first. This provides clear context for selection among siblings.

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?

Description adds context about deletion purpose beyond annotations (destructiveHint, idempotentHint). Mentions clearing sensitive data. No 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?

Two concise sentences, 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?

Single parameter with clear schema, annotations present, description covers usage and pairing - fully 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 100% and description of 'key' in schema is clear. Description doesn't add much beyond schema, but reinforces 'by key'.

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 starts with 'Delete a previously stored memory by key' - clear verb and resource, and differentiates 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?

Explicitly states when to use (stale context, task done, clear sensitive data) and mentions pairing with remember/recall.

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=false. The description adds behavioral context: it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions with annotations.

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

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

The description is concise and well-structured, front-loading the main action and format, then listing use cases. Every sentence adds value, 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 tool's simplicity, full schema coverage, and no output schema, the description is complete. It explains input, process, output format, and use cases adequately for an AI agent to decide when 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?

Schema coverage is 100%, so the schema already documents both parameters with descriptions. The description adds minor context (e.g., max_links defaults 25 max 50) but does not significantly enhance parameter understanding 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 the tool generates a production-ready llms.txt file, fetches a page, extracts key info, and outputs standard markdown. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on the specific llms.txt generation 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 lists three explicit use cases: getting a client's site indexed, drafting your own llms.txt, or auditing a competitor's AI visibility. It provides clear context but does not explicitly state when not to use this tool or suggest alternatives from the sibling list.

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 annotations, such as default behavior (active subscriptions) and optional inclusion of inactive ones. No contradictions with annotations.

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

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

The description is two concise sentences, with the first sentence stating the purpose and return values, and the second providing usage guidance. 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?

For a simple listing tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context fully. Annotations already cover safety and idempotence.

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 does not elaborate on the parameter beyond what the schema provides, but the usage hint indirectly supports 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 verb 'list' and the resource 'subscriptions', and specifies what fields are returned. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description explicitly says when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear guidance and implies 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 a safe, read-only, idempotent operation. The description adds value by specifying batch capability (up to 50 DOIs) and listing returned fields, which are beyond the annotation structure. 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 extremely concise: it fronts key examples and then a clear declarative sentence. Every phrase adds value. No redundancy or unnecessary 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?

Given the simple parameter, full schema coverage, presence of output schema, and rich annotations, the description is largely sufficient. It covers input, output, and batch capacity. Minor missing detail about error handling or partial results, 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 a simple parameter description ('1-50 DOIs'). The tool description repeats this limit without adding new semantics. Examples provided in the description are helpful but do not 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 uses specific verbs ('Get paper info', 'bibliographic details') and resource ('metadata for DOIs'), clearly stating it returns title, authors, year, journal, publisher. It distinguishes from siblings like 'citation' or 'references' by focusing on metadata rather than citation text or reference lists.

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 use for obtaining bibliographic metadata but does not explicitly state when to use this tool versus alternatives like 'citation', 'citations', or 'references'. No exclusion criteria or alternative recommendations are provided.

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

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

The description adds significant behavioral context beyond annotations: it discloses rate limits (5 per identifier per day), that it is free and doesn't count against tool-call quota, and that the team reads digests daily. Annotations only indicate non-read and non-destructive, which aligns with the description. 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, using 4 sentences. It is front-loaded with the primary purpose and then covers usage guidelines, behavioral traits, and constraints. Every sentence provides essential information 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?

Given the tool's simplicity (3 params, no output schema), the description fully covers purpose, usage, parameter guidance, and behavioral notes (rate limits, quota). It leaves no significant gaps for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds extra meaning for the 'message' parameter by advising 'Don't paste the end-user's prompt' and suggesting 1-2 sentences typical. It also reinforces the enum meanings for 'type'. 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 purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists use cases (bug, feature, data_gap, praise) and distinguishes the tool from siblings by being the feedback channel.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises on how to describe the issue and mentions rate limits and quota exemption.

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

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

The description adds significant value beyond annotations: it reveals data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching behavior (5min-1h). Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description fills in concrete operational details.

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 concise sentences plus a bulleted list. Every sentence adds value: one for core functionality, one for use cases, one for technical details. No repetition or filler.

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

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

For a simple read-only tool with one optional parameter, the description covers output content, data source, privacy, caching, and usage context. Annotations cover safety. No output schema is needed; the description sufficiently specifies return format.

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 describes the 'window' parameter with enum values and a brief description. The description adds practical guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides semantic value beyond the schema alone. With 100% schema description coverage, baseline is 3, so 4 reflects the added nuance.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a specifiable window. This distinguishes it from sibling tools like ask_pipeworx (Q&A) and discover_tools (exploration). The verb 'returns' and resource 'trending data' are specific and 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?

Three explicit use cases are listed (discovering hot data sources, confirming popular tool, aligning use case) along with guidance on window selection for hot vs steady-state demand. While excellent, it lacks explicit when-not-to-use or direct alternatives (e.g., discover_tools for broader discovery).

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

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

The description extensively details behavioral traits beyond annotations: required parameters (one of event/topic, else fails), processing details (walks child markets, monotonicity checks, Jaccard similarity ≥0.30, partition filter removing placeholder slugs), and the fill check logic. It also discloses outputs (opportunities array, partition_check) and failure conditions. No contradictions with annotations (readOnlyHint, etc.).

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 requirement and mode explanation, then proceeds to detailed technical information. It is well-structured but verbose; some sections (e.g., partition filter details) could be slightly condensed without losing clarity. Every sentence adds value, but conciseness could be improved for a 1-5 scale.

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, no output schema, and limited annotations, the description is quite complete. It covers input constraints, processing steps, and response structure (opportunities array with fields like gap_pp, suggested_trade, reasoning, partition_check with sum_yes_prices, etc.). However, it does not specify result limits or pagination, which would be useful for a scanning 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?

Despite 100% schema coverage (baseline 3), the description adds substantial meaning: explains the semantic difference between 'event' and 'topic', provides examples (e.g., 'fed-decision-may-2026' for event, 'Fed rate decision' for topic), and details sub-parameters like semantic anchor and partition filter. This goes far 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It explicitly distinguishes between 'event' (single-event mode) and 'topic' (cross-event mode), and the title 'Polymarket Arbitrage' accurately reflects the function. This differentiates it from sibling tools like 'polymarket_fill_risk' and 'polymarket_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 clear guidance on when to use each parameter: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also mentions a fill check condition where realizable_edge_pp <= 0 means 'do not trade it' and directs to 'polymarket_fill_risk' for custom sizing. However, it lacks explicit comparison with other arbitrage-related siblings like 'polymarket_edges'.

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 significant behavioral context: detailed explanation of three segments, models (e.g., crypto_price using lognormal barriers), filters (placeholder-slug, partition overround), caching (1h at KV level), and diagnostics. It also notes that Fed bets are excluded from ranking with justification. This goes well 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 very long (approximately 30 sentences) and dense, though it front-loads the purpose and uses structure (segment enumeration). It could be more concise; many details (e.g., exact model parameters) might be better in separate documentation. It is adequate but not optimally concise for an AI agent.

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 complexity (9 parameters, no output schema), the description is highly complete. It explains the output structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.), and the reason for excluding Fed bets. It provides enough context for an agent to understand what the tool returns and why.

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

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

Schema coverage is 100% with detailed descriptions for all 9 parameters. The description adds some context (e.g., 'Tradeable-edge knobs' for min_liquidity and max_spread_pp) but largely repeats schema information. Baseline 3 is appropriate since the schema already provides strong parameter semantics.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan, return), resource (Polymarket markets), and output (opportunities with discrepancies), making the purpose unambiguous. While it doesn't explicitly distinguish from siblings, the unique focus on Pipeworx data disagreement sets it apart.

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 context with 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' However, it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like the sibling 'polymarket_arbitrage'. The context is clear but lacks exclusions or comparisons.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds specific behavioral details: data sources (daily closes, not intraday), history limits (60-day TTL, snapshot start), and return structure (tracked, expired, snapshots). No contradictions with annotations.

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

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

The description is fairly long but front-loads the purpose and uses structured sections (RESPONSE:). However, it could be more concise by trimming redundant explanations and avoiding inline clarifications.

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 thoroughly explains the return objects (tracked, expired, snapshot_dates) and key fields like trend, decay rate, lifespan. It also covers data freshness and limits. This provides sufficient context for an agent to understand the tool's full 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?

Input schema already describes both parameters with 100% coverage. The description adds default values and maximums (e.g., 'default 14, max 30' for days) which slightly contradict schema's 'clamp 2-30' but provide useful context. Overall, limited additional meaning 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?

The description clearly states the tool provides 'edge persistence and decay telemetry' derived from daily snapshots, and answers specific questions about edge age and shrinkage. It implies differentiation from the sibling 'polymarket_edges' tool but does not explicitly distinguish, so it loses a point.

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 context for when to use the tool (e.g., to differentiate fresh vs. old edges) and explains limits, but it does not explicitly state when not to use it or compare with alternatives. Usage is implied but not explicit.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral details like walking the ladder, clamping size, and return fields for each mode. No contradictions. Minor deduction because annotations already cover safety; description adds context but not critical behavioral disclosure beyond that.

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 structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and uses bold for emphasis. It is somewhat verbose (over 300 words) but necessary given the tool's complexity. A bit of repetition (e.g., 'theoretical overround...not capturable' appears twice) but overall well-organized.

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

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

No output schema exists, so the description thoroughly covers all return fields for both modes, including edge cases like 'thin_legs' and 'forced_directional_risk'. It also explains decision logic (default side for basket) and provides risk warnings. The description is complete 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 coverage is 100%, but the description significantly enhances parameter understanding: explains mutual exclusivity of market/event, default side logic for basket, and the dual interpretation of size_usd (spend vs target for single, settlement notional for basket). Also mentions defaults and clamping. This goes well 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 it performs a realizable vs theoretical edge check against live order-book depth. It distinguishes two modes (single-market and basket) and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why (theoretical overround not capturable, partial fills cause unhedged positions) and states parameter requirements (one of market or event).

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, and idempotentHint. The description adds extensive behavioral context: compatibility_warning cases, temporal alignment, skipped cross-type/subtype counters, and the caveat that pre-mapped does not guarantee tradeability. 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 well-organized with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. While verbose, each sentence adds value. Could be slightly more concise but appropriate for the 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?

Despite no output schema, the description explains the response structure (leg prices, top_spreads_pp, safety fields) and error cases. It covers temporal alignment and skipped comparisons, providing a complete picture of the tool's behavior and 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%, baseline 3. The description adds significant value by explaining the topic parameter's 10 shortcuts with examples, defining explicit parameters' override behavior, and providing context on how each parameter affects the query.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from sibling tools like polymarket_arbitrage by specifying venue pair and includes specific modes and response details.

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 two usage modes (topic shortcuts and explicit pairing) and cautions that most pre-mapped topics return compatibility warnings. It provides context on when spreads are meaningful but does not explicitly state when not to use the tool or compare to 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 provide read-only, idempotent, and non-destructive hints. The description adds value by clarifying scoping to the agent's identifier and pairing with other tools.

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, each serving a distinct purpose: action, usage rationale, and scope. No fluff, front-loaded with the main 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?

Given the simple tool (one optional parameter, no output schema), the description fully covers behavior, scope, and pairing, leaving no gaps 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?

Schema coverage is 100% with a clear description for the single parameter. The description adds behavioral nuance (omit to list all keys), enhancing understanding.

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 saved value or lists all keys, using specific verbs and distinguishing 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?

Explicitly states when to use (look up previously stored context) and provides context about scoping and pairing with remember/forget for save/delete operations.

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?

Description details return fields and side effects like marking events read. However, it contradicts the readOnlyHint annotation (true) by describing a write operation (mark_read), which undermines 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?

Four focused sentences with no redundancy. Front-loaded with purpose, then parameter details and alternate access. Excellent conciseness.

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

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

Covers output fields, filtering, polling, and alternative access. Lacks output schema but compensates with field descriptions. The annotation contradiction slightly diminishes 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?

Adds value beyond the 100%-covered schema: clarifies limit range (1-200), the meaning of mark_read, and the format of citation_uri. Schema descriptions are good, but description enhances understanding.

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?

Clear and specific: 'Pull fired events from your subscription feed.' Describes returned fields and filtering options, effectively distinguishing from sibling 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?

Provides guidance on polling and suggests an alternative HTTP endpoint. Also explains the effect of mark_read for subsequent calls, but does not explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds valuable behavioral context: it fans out to multiple sources in parallel, has fallback logic (GDELT → GNews on rate limit/5xx), soft-fails on PatentsView, and returns structured changes grouped by source with citation URIs. No 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 a single dense paragraph that front-loads with example queries. It includes all necessary details but is somewhat lengthy (6 sentences). Every sentence earns its place, though slight restructuring could improve readability. Still concise for the amount of 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 no output schema, the description explains the return structure (changes[] grouped by source, total_changes, citation URIs). It covers all three data sources, fallback, limitations, and the contrast with entity_profile. The tool is complex (multi-source), and the description fully addresses the agent's needs.

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 describes all 3 parameters with 100% coverage. The description adds context: 'since' accepts ISO date or relative shorthand ('7d','30d','3m','1y') with recommendation '30d' or '1m', and 'value' can be ticker or CIK. This enhances the agent's 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 provides a change feed for a company (SEC filings, news, patents) within a time window. It uses specific verbs like 'fans out' and lists concrete data sources, and distinguishes itself from the sibling tool 'entity_profile' by contrasting with static profile queries.

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

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

Explicit guidance is given on when to use this tool (e.g., 'What's new with X', 'latest on Y') and when to use the alternative 'entity_profile' instead ('Use entity_profile instead when you want the static profile...'). Also describes fallback behavior between GDELT and GNews, and limitations like PatentsView API sunset.

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, idempotentHint, etc. The description adds the behavioral context of citation-graph traversal, which aligns. No additional behaviors like pagination or rate limits are disclosed.

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: a single sentence with examples and a usage clause. No extraneous information; front-loads 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?

For a simple one-parameter tool with an output schema and rich annotations, the description is complete. It specifies input, output (DOIs cited), and use cases.

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 description coverage, the description compensates by explaining the parameter 'DOI' as the input paper and providing examples. It adds meaning beyond the bare 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 returns DOIs cited by the given DOI (reference list). It uses specific verbs and examples like 'references in [paper]' and distinguishes from the sibling 'citations' which likely does the opposite.

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 mentions use cases like citation-graph traversal and literature review, but does not directly contrast with the sibling 'citations' tool to indicate when to use each. There is no 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, idempotentHint, etc., so the bar is lower. The description adds that it returns a count (fast version), which 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?

Two sentences that are front-loaded with queries and provide all necessary information without waste. Extremely 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 tool with one parameter and an output schema, the description fully explains what to expect and when to use it, making it 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 description coverage is 0%, but the description compensates fully by providing example usage and teaching the agent how to invoke the tool with a DOI. The single parameter is well contextualized.

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 specific verbs and resources: 'count outgoing references for a DOI', and distinguishes from the sibling `references` by calling itself a 'fast version'. The example queries further clarify 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?

The description provides explicit usage queries and clearly states when to use this tool ('when you only need the number') and implies the alternative (`references`) for when the full list is needed.

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 (idempotentHint true, destructiveHint false), description adds critical context: key-value scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous. 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?

Four sentences, each serving a purpose: stating purpose, giving usage conditions, explaining scoping/persistence, and linking to sibling tools. Well structured and front-loaded.

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 full schema coverage and no output schema, description provides sufficient behavioral context (scoping, lifetime) and usage guidance for correct agent invocation.

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

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

Schema coverage is 100% with clear descriptions for key and value. Description adds no additional semantics beyond confirming key-value pair usage, meeting baseline but not exceeding.

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 reuse across conversations or sessions, with specific verb 'Save' and resource 'data'. It distinguishes from siblings by mentioning pairing with recall 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?

Explicitly states when to use: when discovering something worth carrying forward, with examples like resolved ticker or user preference. Also implies alternatives: recall for retrieval, forget for deletion.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that each call cascades through multiple endpoints and replaces manual lookups, providing useful internal behavior 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 somewhat lengthy but front-loaded with purpose and examples. Every sentence adds value, though minor redundancy exists. Efficient for the amount of information provided.

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

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

Given no output schema, the description compensates by explaining return values for both types and the internal cascading. Missing error handling details, but overall complete for a lookup 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%, but the description greatly enriches parameter semantics by specifying exact return fields (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand for drug) and auto-disambiguation for company input.

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

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

The description clearly states the tool resolves names to canonical IDs, uses specific verb 'resolve' and resource 'name to ID'. It distinguishes from siblings by noting it replaces 2-3 manual lookups, and provides example queries and supported types.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It details supported types but does not explicitly mention when not to use or alternatives, though the context of siblings makes that less critical.

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, idempotentHint, openWorldHint, and non-destructive hint. The description adds value by revealing it uses ai_visibility_check under the hood, ranks by score, and returns confidence and signal density, going beyond annotation metadata.

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

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

Two highly informative sentences with no filler. First sentence captures core function; second adds use case and output details. Every clause 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?

Given moderate complexity (4 params, no output schema), the description covers input semantics and output shape (ranked list with score, confidence, signal density). It lacks explicit mention of entity limits or caching, but the annotations compensate for safety traits. Sufficient for agent 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?

Schema description coverage is 100% (all parameters documented). The description adds pragmatic context: first entity is treated as 'subject', models list includes free vs paid options, and context disambiguates common names. This supplements the schema 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 the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks them, and identifies most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic 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?

The description gives a concrete use case ('competitive AI-marketing audits') and an example question. It doesn't explicitly state when not to use or list alternatives, but the context is clear enough for an agent to infer typical scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds significant behavioral details like composite nature, partial failures, and bundlephobia timing (5-30s). This goes 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 front-loaded with core purpose and is structured clearly. It is somewhat verbose but every sentence adds value. Could be slightly more concise without losing 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 (multiple sources, partial failures) and no output schema, the description thoroughly explains return values and behavior. It covers everything an agent needs to understand the output and 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 covers both parameters with descriptions (100% coverage). The description adds no new semantic details about parameters beyond the schema, but it provides useful context for how the tool uses them. 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's purpose as a composite check for adding npm packages, combining deps.dev and bundlephobia. It distinguishes itself from siblings by specifying the NPM ecosystem and noting alternatives for other ecosystems.

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

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

The description explicitly says when to use (e.g., 'is X safe/popular/small') and provides context for NPM-only usage with fallback. It lacks an explicit when-not, 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 show readOnlyHint, idempotentHint, and non-destructive. The description adds significant behavioral details: embedding model, window size, character cap with truncation warning, and offset inclusion for verification. These go well beyond annotations, giving agents a clear understanding of latency, memory, and verification capabilities.

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 paragraph of ~4 sentences with no wasted words. Front-loaded with purpose and usage, then technical details. Every sentence earns its place: usage guidance, pairing, embedding mechanics, and limitation. Highly efficient for the amount of 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 no output schema, the description fully explains return value (passages with offsets and scores). Covers limitations (200K char cap with truncation flag) and pairing with sibling tool. All key aspects—purpose, usage, inner workings, output, constraints—are addressed.

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 clear descriptions. The description adds value by explaining the 'text' parameter as 'already pulled' data, giving natural-language query examples, and clarifying the limit's role (max passages). Though schema already defines basics, the description's examples and contextual framing improve parameter comprehension.

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?

Explicitly states 'semantic search INSIDE a fetched record' and gives concrete examples (SEC 10-K, article, tool result). Clearly distinguishes from siblings by naming ask_pipeworx_grounded and explaining the pairing. The verb 'search within' is specific and resource-oriented.

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 ('too big to cram into the prompt') and what it achieves ('saves context, returns only passages that matter'). Provides an alternative sibling (ask_pipeworx_grounded) and explains how they work together. No ambiguity about 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 indicate readOnlyHint=false and destructiveHint=false. Description adds rich behavioral context: returns subscription id, requires auth, delivery constraints (email validation, phone verification, 10/day SMS cap, webhook auto-disable after 10 failures), and type-specific filter details.

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 paragraph front-loaded with core purpose, but dense with details. Could benefit from bullet points for subscription types, but remains concise overall.

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 creation behavior, parameter details, delivery channels, and return value. Lacks explanation about updating or deleting subscriptions, but these are likely handled by sibling tools. Complete for a creation 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?

Input schema covers all parameters with descriptions. The tool description adds examples for each type (e.g., items codes for sec_8k, topic for polymarket_edge) and clarifies required vs optional fields, enhancing 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?

Description clearly states verb 'Create', resource 'proactive monitoring subscription', and action 'to a live-data event stream', distinguishing from sibling tools like list_subscriptions and unsubscribe.

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

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

Explicitly mentions context (proactive monitoring), prerequisite (Pipeworx OAuth account), and supported subscription types with examples. Lacks explicit when-not-to-use, but the clear context compensates.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is clear. The description adds value by specifying the output format (category-bucketed example questions with exact tool+argument shapes from the live catalog), which is not covered by 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 paragraph that is information-dense but well-structured, starting with common user queries and then explaining the tool's purpose and behavior. It is slightly long but every sentence adds value, and the front-loading with alternative phrasings helps quickly orient the agent.

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 low complexity (1 optional param, no output schema, many annotations), the description is complete. It covers what the tool does, when to use it, what arguments to pass, and what kind of output to expect, leaving no significant gaps for an agent to interpret.

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 for the single parameter 'topic', describing its type and possible values. The description adds further meaning by explaining the effect of omitting the parameter ('for full spread') and passing specific values ('to focus'), which goes 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 defines the tool as an onboarding entry point that returns categorized example questions. It uses specific verbs and resources ('returns category-bucketed example questions') and distinguishes itself from sibling tools like ask_pipeworx and entity_profile by being the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

The description explicitly states when to use it ('use this FIRST when you do not yet know what Pipeworx can do for you'), provides guidance on arguments (no args for full spread, topic for focus), and mentions alternatives (meta-tools like ask_pipeworx, entity_profile, etc.), giving clear usage 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?

Adds value beyond annotations by explaining 'deactivated (not deleted)' and ownership enforcement. Annotations already indicate non-destructive and idempotent; description confirms and adds 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?

Two sentences with zero waste. First sentence states action and parameter; second sentence adds key behavioral notes. Efficient and front-loaded.

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 1 param and no output schema, description is complete: explains effect, ownership, and impact on historical data. Slightly lacking success response detail, but 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 3. Description does not add additional parameter info beyond schema's 'Subscription id (uuid) returned by subscribe.'

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 'Cancel a subscription by id', with specific verb 'Cancel' and resource 'subscription'. It distinguishes from sibling 'subscribe' by mentioning ownership enforcement and deactivation behavior.

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

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

States explicit ownership condition ('you can only cancel your own subscriptions'), guiding when to use. Lacks explicit comparison to siblings like 'list_subscriptions' or 'subscribe', but condition 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context about the underlying data sources (SEC EDGAR + XBRL), the return format (verdict, structured form, actual value with citation, percent delta), and the supported claim types. This goes beyond 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 thorough but slightly long. It is front-loaded with the core purpose and usage examples, followed by specifics. Every sentence adds value, but could be more concise. However, it remains 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?

Given the tool has one parameter and no output schema, the description thoroughly explains the return format, supported domain, and behavioral traits. It covers all necessary context for an agent to understand when and how to use the tool correctly.

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

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

The input schema has one parameter with 100% description coverage. The description adds meaning by providing examples of natural-language claims (e.g., 'Apple's FY2024 revenue was $400 billion') and clarifying the expected format. This enhances the schema 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 clearly states the tool's purpose: to verify natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. It distinguishes from siblings by noting it replaces 4-6 sequential calls, making the tool's unique value clear.

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 whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported domain (company-financial claims for public US companies). However, it does not explicitly state when not to use it or describe alternatives beyond hinting at the replaced sequential calls.

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