Fara

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

Annotations already declare the tool as read-only and idempotent. The description adds important behavioral details: the default model is free, Anthropic requires a BYO key, and the output shape includes 'score, confidence, signals, raw_response'. 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 sentences, front-loaded with the main purpose, and 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 4 parameters, no output schema, and no nested objects, the description is complete. It explains all inputs, default behavior, optional key, and return structure. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it clarifies the default model, explains that '_apiKey' is optional and only needed for Anthropic, and that 'context' helps disambiguate. This surpasses the baseline.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs') with a clear output ('score visibility 0-100 per model'). It distinguishes from sibling tools by focusing on AI visibility scoring, which is unique among siblings like 'deep_research' or 'scan_competitor_ai_presence'.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not list when not to use or alternatives, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it returns structured answers with stable pipeworx:// citation URIs, which is valuable behavioral context beyond annotations.

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

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

The description is informative but somewhat lengthy due to listing many domains and examples. It is well-structured and front-loaded with the key 'prefer over web search' guidance, but could be slightly more concise.

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 (3,725 tools, no output schema), the description adequately covers purpose, usage, and return format (structured answers with citations). It does not explain what happens if the question cannot be routed, but it is complete enough for the 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 100% with a clear parameter 'question' and multiple aliases listed. Description does not add additional meaning beyond what the schema provides, but it clarifies that input should be a natural language question.

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 routes questions to a vast set of tools (3,725) across 881 sources and returns structured answers with citations. It distinguishes itself from web search and sibling tools by emphasizing authoritative structured data.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and lists specific query types (SEC filings, FDA data, etc.). Provides concrete examples of when to use, such as factual questions about real-world entities, events, or numbers.

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 internal process: routes to correct tool, fills arguments, fetches data, extracts answer only from tool result. Lists explicit refusal reasons. Annotations already indicate readOnly, openWorld, idempotent; description adds detail 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?

Front-loaded with purpose, follows with details and usage. Compact at ~120 words with no redundant sentences. Every sentence adds value.

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

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

With no output schema, description fully explains return structure (success and failure cases, including refusal reasons). Covers cost comparison and when to use, making it complete for decision-making.

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

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

Schema description coverage is 100%, so description adds little beyond schema. It states 'Your question in natural language' which is already captured. 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads. Explains routing, extraction process, and output format. Distinguishes from sibling ask_pipeworx by specifying it is for casual 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 provides when to use (answers to be quoted, cited, acted on, no invented facts) and when not to prefer ask_pipeworx for casual lookups. Includes cost trade-off explanation.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by detailing safety mechanisms (low-confidence short-circuit, closed market status, illiquid wide-spread flags), resolution-rule risk parsing, and fan-out logic. It fully discloses edge cases that affect tool behavior and results interpretation.

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 notably long (5+ paragraphs) but each sentence adds unique information. It is well-structured with capital-letter section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) that improve scanability. While lengthy, the complexity of the tool justifies the thoroughness.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively covers all aspects: required inputs, response structure (market, analysis, evidence), error states (low_confidence_match, market_closed_or_inactive), safety notes, and even resolution-rule risk. An agent can fully understand the tool's behavior and 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?

The input schema already covers all three parameters with descriptions, but the description adds significant value: it explains how depth affects fan-out, when to use include_raw for large payloads, and provides examples for the market parameter. This goes beyond the schema's basic definitions.

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

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

The description opens with a clear verb-resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists specific use cases and distinguishes itself from sibling tools by focusing on a single Polymarket bet research task, with explicit classifier examples and fan-out 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?

The description provides explicit usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and gives multiple input formats. However, it does not explicitly contrast with sibling tools like ask_pipeworx or polymarket_edges to clarify when to use this one over alternatives.

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

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

Annotations mark the tool as read-only and non-destructive. The description adds valuable behavioral context: details about data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. No contradiction with annotations.

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

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

The description is somewhat lengthy but well-structured: starts with common user query examples, then states purpose, then explains data sources and behavior. Slightly verbose but efficient for the complexity; front-loaded with key usage signals.

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 return format (paired data + citation URIs) and mentions sorting. With only 2 parameters and high schema coverage, there is no missing critical information for agent invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining what each 'type' value retrieves (financial data vs. adverse event counts) and providing examples for 'values' (tickers/CIKs for companies, drug names). Overall adds moderate value.

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

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

The description uses specific verbs like 'compare', 'pull', and 'returns' and clearly states the tool does side-by-side comparisons of 2-5 companies or drugs in a single parallel call. It distinguishes from sequential single-pack lookups and provides concrete examples of user queries ('compare X and Y', 'which is bigger', etc.), making purpose unambiguous.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear guidance on when to prefer this tool over alternatives. It also mentions it replaces 8-15 sequential lookups, reinforcing efficient 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds key behaviors: grounded answers with verbatim evidence, confidence, source, citation, explicit gaps array for unanswered facets, never invents. Discloses 15-60s timing, account requirement, and paid plan for thorough depth.

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?

Efficiently written with a strong front-loaded main statement, followed by well-organized details. Every sentence adds distinct value: decomposition description, parallel routing, return format, usage guidance, requirements, and timing.

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

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

For a complex multi-source research tool with no output schema, the description is remarkably complete. Covers input interpretation, output format (structured findings packet with evidence, gaps), prerequisites (account, paid plan), and expected latency. Provides all necessary context for an agent to use 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?

While schema provides 100% coverage, the description adds significant meaning: explains that depth maps to number of facets (quick=3, standard=5, thorough=8) and that thorough requires a paid plan, going beyond basic schema descriptions.

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

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

The description clearly states the tool's purpose as 'Grounded multi-source research in ONE call' and explains its decomposition and parallel routing behavior. It distinguishes itself from sibling tool ask_pipeworx by specifying that deep_research is for broad/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 tells when to use: 'Use for broad or multi-part questions'. Explicitly tells when not: 'use ask_pipeworx for single lookups'. Also mentions account requirements and depth limitations, providing clear context for agent decision-making.

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, destructiveHint=false. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This is valuable behavioral context beyond the annotations.

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

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

The description is four sentences, front-loaded with the core purpose. Every sentence adds information: purpose, example domains, return value, strategic usage advice. Could be slightly more concise but 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 no output schema, the description adequately describes that it returns tool names, descriptions, and full input schemas with examples. It also covers strategic usage (call FIRST). For a discovery tool with many siblings, this is complete.

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

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

Schema coverage is 100% and schema definitions are clear. The description adds value by listing example queries and explaining that multiple aliases (task, q, search, description) are accepted for the 'query' parameter. This helps agents understand flexibility in parameter naming.

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 'Find tools by describing the data or task' with specific verb and resource. It lists many example domains (SEC filings, FDA drugs, etc.), making the tool's scope unmistakable. It is well differentiated from sibling tools which are focused on specific tasks or domains.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This is clear guidance on when to use this tool vs. directly calling a specific tool. No exclusions are needed given the universal discovery role.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: fans out across multiple sources, returns specific fields, notes patents API may sunset and soft-fails, and mentions concurrency. 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 but packs a lot of information efficiently. Each sentence adds value, starting with examples followed by guidance and details. Could be slightly restructured but is largely concise.

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, so description must cover return values. It lists all fields returned (cik, company_name, recent_filings with URIs, fundamentals sorted, patents with sunset note, news via fallback, LEI). Comprehensive for a complex tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description reinforces the constraint that names are not supported and to use resolve_entity, but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to provide a full cross-source profile of a US public company in one parallel call. It gives example user queries and lists specific data sources and fields returned, distinguishing it from sibling tools like resolve_entity.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises to use resolve_entity if only a name is available, providing both when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not elaborate on permanence, undo capability, or authorization requirements. Given annotation coverage, a score of 3 is appropriate.

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

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

The description is extremely concise at two sentences, with the primary action stated first. Every sentence serves a purpose without unnecessary elaboration.

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

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

For a simple tool with one parameter and no output schema, the description covers the purpose, usage scenarios, and pairing. Minor lack of detail about post-deletion behavior or return values, but overall sufficiently complete.

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

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

Schema coverage is 100% and the single parameter 'key' is adequately described in the schema as 'Memory key to delete'. The description does not add additional semantic meaning beyond what the schema provides, resulting in baseline score.

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 verb 'Delete' and resource 'memory by key', clearly stating the tool's function. It distinguishes itself from siblings by explicitly mentioning 'remember' and 'recall' as paired tools.

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

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

The description provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also advises pairing with 'remember' and 'recall', guiding sibling tool selection.

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

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

The description adds significant context beyond annotations: it explains that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown as a single text blob. This complements the readOnlyHint, openWorldHint, and idempotentHint annotations 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 two substantive sentences plus a bullet-list of use cases. It is front-loaded with the core action and output format. Slight improvement could be avoiding the colon-semicolon structure, but overall efficient.

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

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

Given no output schema, the description adequately describes the return value (single text blob in standard llms.txt markdown). It covers what the tool does and its output format. However, it lacks details on error handling or behavior for edge cases (e.g., if the URL is unreachable), but completeness is appropriate for this task.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add new meaning to parameters beyond the schema; it only implies that max_links controls the number of link entries. The description's mention of 'key links' might indirectly clarify the parameter's purpose, but no explicit mapping.

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 ('Generate', 'Fetches', 'extracts') and clearly identifies the resource (llms.txt file for any URL). It distinguishes from sibling tools by focusing on this specific output format for AI crawlers, which is unique among the listed siblings.

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

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

The description explicitly states three use cases (getting a client's site indexed, drafting for own project, auditing competitors), which helps an agent decide when to invoke it. However, it does not mention when not to use it or provide comparisons to alternative sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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 result cap, client-side filtering, PDF URLs, and keyless access. Complements annotations (readOnly, openWorld, idempotent, non-destructive) 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?

Four sentences, front-loaded with primary purpose. No filler; every sentence adds value.

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

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

Describes return structure (rows linking to foreign principal/country with PDF URL) and document types. Missing pagination details, but adequate for a list tool with no output schema.

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

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

Schema coverage is 100%, but description adds context: registration_number source, limit defaults/cap, filtering method. Adds value beyond schema.

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

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

Clearly states verb 'List', resource 'FARA filings', and required parameter 'registration_number'. Mentions document types and links to foreign principal/country. Distinguishes from sibling 'search_registrants' by specifying it as prerequisite.

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 client-side filtering and result cap. Implies prerequisite workflow with 'from search_registrants'. Lacks explicit when-not-to-use or alternatives, but sufficient for context.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that the API is keyless and that filters are applied client-side, which is useful beyond the annotations. 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, well-structured paragraph with clear sentences. Every sentence adds value: the main purpose, the prerequisite step, optional filters, output fields, and authentication status. No redundancy.

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

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

Given the tool's simplicity and the presence of annotations and full schema coverage, the description is complete. It covers the input, how to obtain it, optional parameters, output fields, and API key requirements. No gaps.

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

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

Schema coverage is 100%, granting a baseline of 3. The description adds meaning by clarifying that name and country filters are client-side substring searches and that status='terminated' returns former relationships. It also explains that registration_number comes from search_registrants.

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 that the tool lists foreign principals (foreign governments, parties, companies, individuals) for a given FARA registrant. It uses a specific verb ('List') and resource ('foreign principals'), and distinguishes from sibling tools like search_registrants by explaining the need for a registration number.

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 context on when to use: after obtaining a registration_number from search_registrants. It explains optional client-side filtering and status setting. However, it does not explicitly exclude alternative tools or scenarios, missing some guidance on 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?

Adds value beyond annotations by specifying default behavior (active only) and return fields. Annotations already cover readOnly, idempotent, destructive, openWorld.

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 efficient sentences: purpose+fields, then 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?

No output schema, but description lists all return fields. Provides usage guidance. Complete for a read-only list 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 covers 100% of parameters, so description needs no extra. Parameter include_inactive is documented in schema; description implies default behavior.

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

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

Description clearly states 'List the caller's active subscriptions' and enumerates returned fields. Distinguished from siblings 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?

Explicit advice: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides context but lacks explicit 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?

Discloses that feedback is read daily by the team, affects roadmap, and is rate-limited to 5 per identifier per day. No contradiction with annotations, which are minimal (no read-only, destructive, idempotent hints). Adds behavioral context beyond annotations.

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

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

The description is a single dense paragraph with no wasted words. Every sentence adds value: purpose, usage, how to write, team behavior, rate limits, quota impact. 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?

For a feedback submission tool, the description covers all essential aspects: what it is for, when to use each type, how to provide effective feedback, and constraints (rate limit, no quota impact). No output schema is expected for such a 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 description adds extra context: explains enum values in more detail, advises to describe issues in terms of Pipeworx tools/packs, and not to paste end-user prompts. This goes beyond the schema descriptions.

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

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

The description clearly states it is for sending feedback about bugs, features, missing data, or praise. It distinguishes itself from sibling tools by focusing on feedback, not data retrieval or analysis.

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

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

Explicitly specifies when to use each feedback type (bug, feature, data_gap, praise) and provides guidance on what not to do (don't paste end-user's prompt). Also mentions rate limits and that it is free and doesn't count against quota.

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, idempotentHint, etc. The description adds caching behavior (5min-1h depending on window), which is useful beyond annotations. 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 yet packed with information, using bullet points for use cases. No wasted words; every sentence adds value.

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

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

Given the tool's simplicity (one optional parameter, no output schema needed), the description covers return values (top tools, packs, volume), data source, and caching. It is fully sufficient for an agent to understand 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 one enum parameter. The description adds value by explaining the difference between short and long windows ('surface what's hot right now' vs 'steady-state demand'), beyond the schema's bare 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 returns top tools, top packs, and total call volume over recent windows. It uses a specific verb ('Returns') and resource, distinguishing it from sibling tools like 'discover_tools' or 'ask_pipeworx' which serve different purposes.

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 provided (discovering hot data sources, confirming popular choice, aligning use case). It does not explicitly state when not to use or name alternatives, but the context is clear. Slight deduction for missing exclusion criteria.

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?

Describes algorithms (monotonicity checks, partition_sum, Jaccard similarity, fill check against CLOB depth) and response structure in detail. Annotations (readOnlyHint etc.) are consistent; 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?

Well-organized and thorough, but slightly dense. Every sentence adds value, though length may reduce scanability.

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 inputs, modes, algorithm details, response fields, fill check, and references to sibling tools. No output schema but description fully compensates.

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%; description adds substantial context beyond schema: explains mode behavior, gives example inputs, and clarifies event vs topic usage.

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 using monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and uses specific verbs like 'find' and 'scan'.

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 requires one of event or topic, recommends event for specific markets and topic for cross-event scanning. Provides examples and warns when not to trade (fill check shows no realizable edge). References sibling tool for custom sizing.

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 and idempotent, but the description adds extensive behavioral details: caching at KV level for 1 hour, data sources (FRED, GDELT), model algorithms, edge calculation with slippage, Kelly sizing, and full response structure including diagnostics.

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 verbose, including detailed model mechanics (e.g., formula for edge_pp_net). While well-organized into segments, it could be more concise by moving some technical details elsewhere.

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 the response structure: three segments under by_segment, fed_candidates/note, and _diagnostics. It also covers edge cases (empty segments, filter skips) and caching 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?

With 100% schema coverage, baseline is 3. The description adds context beyond the schema: explains purpose of each knob (e.g., 'skips opportunities too small to bet sensibly' for min_kelly) and provides usage recommendations (e.g., 'drop to 0 if you have a smarter fill model' for slippage_pp).

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 a clear verb ('scan') and resource ('Polymarket markets'), with a well-defined purpose: returning opportunities where Pipeworx data disagrees with market price. It differentiates from sibling tools by focusing on disagreements and providing specific model families.

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 the use case ('what should I bet on today') and that agents use it for discovery without paging. It does not explicitly say when not to use it or compared to siblings, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: bounded by 60-day TTL, not intraday, response structure details, and decay computation from daily closes. 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 detailed but not overly long; it front-loads the core purpose and then explains response fields and limits. Every sentence adds value, though slightly verbose in the parameter and response explanations.

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 response structure (tracked, expired, snapshot_dates, subfields) and limitations (60-day TTL, decay from daily closes). Complete enough for an AI agent to understand tool behavior and expectations.

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

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

Schema has 100% coverage for 2 parameters. The description reinforces defaults (days default 14, max 30; window default '1wk') and explains their role within the edge tracking context, adding value beyond schema.

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

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

The description uses specific verbs like 'edge persistence and decay telemetry' and clearly states what the tool does: answers 'how long has this edge existed and is it shrinking?' It distinguishes from sibling tools by contrasting fresh vs old 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 implies when to use this tool (to assess edge persistence) and provides context like 'A fresh wide edge and a 3-week-old wide edge are different trades.' It does not explicitly list alternatives but the purpose is clear enough to differentiate from 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), and in basket mode identifies forced_directional_risk legs. 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?

Description is long but well-organized with clear sections (REQUIRES, SINGLE-MARKET, BASKET). Front-loaded with core purpose. Every sentence adds essential information for an AI agent. Structure is logical and easy to parse.

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

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

No output schema, but description explicitly lists all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk for basket). Also warns about partial fill risks, making it complete for an edge-check tool.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema: explains size_usd interpretation differs by mode (max spend vs target proceeds), default side auto-detection for basket mode, and clamp range (10–1,000,000). Adds value that the schema alone does not convey.

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 CLOB order-book depth'. It distinguishes between single-market and basket modes with explicit return fields, and contrasts with sibling tools by specifying when to use this check.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround on thin books not capturable, partial basket fills create unhedged positions). Provides clear when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=true. The description adds substantial behavioral context: compatibility_warning conditions, temporal_alignment field, skipped cross-type/subtype counters, and the fact that real spreads are rarer than suggested. 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 lengthy but well-structured with bold section headers, lists, and examples. It front-loads the core purpose and then details modes, response fields, and safety notes. Each sentence adds value, though it could be slightly tighter.

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

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

No output schema exists, so the description must explain the output, which it does thoroughly: leg-by-leg prices, matched spreads, safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers edge cases like non-equivalent bet shapes and temporal gaps, making the tool fully understandable despite the complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description aggregates the parameters into two modes but does not add new syntax or format details beyond what the schema provides. Examples in the schema's 'examples' array already show usage.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' providing a specific verb (compute spread) and resource (two venue prices). It clearly distinguishes from siblings like 'polymarket_arbitrage' which focuses on single-venue 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?

It explains two explicit modes and when to use each. It warns that most pre-mapped topics return a compatibility warning and that 'pre-mapped ≠ tradeable.' However, it does not explicitly state when not to use the tool or name alternatives beyond 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: scoped to identifier (anonymous IP, BYO key hash, or account ID) and the omission behavior. 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?

Five sentences, each serving a purpose: action, usage context, scope, pairing. No redundancy, front-loaded with core functionality.

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 one optional parameter, no output schema, and annotations covering safety, the description fully explains usage, scope, and pairing. No gaps remain for an agent to effectively use the tool.

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

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

Only parameter 'key' has a schema description. The description adds meaning by stating 'omit to list all keys', which covers the omission behavior. Schema coverage is 100%, so the description adds sufficient value.

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

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

The description clearly states it retrieves a value saved via remember or lists all keys when omitted. It distinguishes from siblings remember and forget by specifying its role as retrieval.

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

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

Explicitly says when to use (look up context stored earlier) and implies when not (omit key to list all). Mentions pairing with remember and forget but does not explicitly exclude other 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 indicate read-only, idempotent, non-destructive behavior. The description adds key behavioral context: mark_read effects on subsequent calls (cursor advancement), that the feed is persisted, and that the same data is available via a direct URL. 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?

Four sentences, each purposeful. Front-loaded with purpose, then details on parameters, behavior, and alternative access. No redundant or vague language.

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

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

For a tool with no output schema, the description adequately explains return values (source, citation_uri, raw payload) and usage patterns. Minor omission: lacks mention of result sorting order (implied most recent) and error handling, but overall sufficient.

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

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

Schema coverage is 100% with parameter descriptions. The description reinforces parameter use (e.g., 'Filter by type and/or since') and explains the effect of mark_read and unread_only beyond schema definitions, adding value.

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

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

The description begins with 'Pull fired events from your subscription feed' and specifies returned fields (source, citation_uri, raw event payload), clearly stating the tool's function. It distinguishes itself from sibling tools like list_subscriptions by focusing on retrieving actual events rather than managing subscriptions.

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

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

The description provides clear usage context: filtering by type/since, using mark_read to advance cursor, and notes that polling works fine. It also mentions an alternative HTTP endpoint for scripts, but does not explicitly state when not to use this tool versus 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds multi-source fan-out (SEC EDGAR, GDELT/GNews, USPTO), fallback behavior, and soft-fail details, exceeding annotation 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?

Description is a single dense paragraph but well-organized, front-loading examples and core purpose. Could benefit from minor structural breaks (e.g., bullet points) but remains 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?

Despite no output schema, description explains return structure (changes[] grouped by source, total_changes, citation URIs) and covers multi-source aggregation complexity. Complete for a read-only data retrieval 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 covers all 3 parameters with descriptions (100% coverage). Description adds usage examples for 'since' (ISO date vs relative shorthand) and clarifies entity type limitation, providing extra value beyond baseline.

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

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

The description clearly states it provides a change feed for a company, with example queries like "What's new with X" and explicitly distinguishes from sibling tool entity_profile for static profiles.

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

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

Provides explicit when-to-use examples and direct alternative (entity_profile) for static profile, with clear differentiation. This is model guidance.

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

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

Annotations already indicate idempotentHint=true. Description adds valuable context beyond annotations: scoped by identifier, persistent vs 24-hour retention, and that it's non-destructive (save operation). No contradictions.

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

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

Three sentences covering all essential aspects: purpose, usage, scoping, persistence, and sibling tools. No redundant or unnecessary words.

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

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

For a simple tool with only two string parameters and no output schema, the description is complete. It explains purpose, when to use, scoping, persistence, and how to pair with related tools.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description doesn't add new information beyond the schema, which is acceptable given high coverage. Baseline 3.

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

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

Clearly states 'Save data the agent will need to reuse later' – specific verb and resource. Distinguishes from sibling tools recall and forget by explicitly naming them.

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

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

Provides explicit when-to-use guidance: 'when you discover something worth carrying forward' and pairs with recall/forget. Also mentions scoping and persistence duration for different user types.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context about cascading internal lookups and auto-disambiguation. It also details return fields for each type. No annotation contradiction. Slight gap: does not describe behavior on unrecognized input or error handling.

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 example queries, then stating purpose, then detailing types. It is informative without being verbose. However, it could be slightly more condensed; some phrases (e.g., 'auto-disambiguated') could be simplified.

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

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

With no output schema, the description adequately explains return values for both entity types, including citation URIs. It also mentions the internal cascading lookup, providing sufficient context for an agent to understand the tool's operation and output.

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 significantly enhances parameter understanding. For the 'type' parameter, it explains what each enum value returns. For 'value', it clarifies accepted formats (ticker, CIK, name for company; brand/generic for drug) and gives concrete examples. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It uses specific verbs ('resolve', 'look up') and provides example queries. The tool is well-distinguished from siblings by its unique function of mapping names to IDs.

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

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

The description explicitly advises to 'Use FIRST whenever you have a name but need an ID', providing clear guidance on when to use. It also explains that the tool replaces manual lookups. However, it doesn't explicitly mention when not to use or suggest alternative sibling tools for cases where an ID is not the goal.

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 valuable behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. However, it does not disclose potential rate limits or authorization requirements beyond the _apiKey parameter.

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

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

The description is three sentences long with no wasted words. The first sentence states the primary function, the second explains the mechanism, and the third provides a use case. It is front-loaded and efficient.

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

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

Given the absence of an output schema, the description adequately lists the return fields (ranked list with score, confidence, signal density). It covers all necessary behavioral and usage context for a tool with 4 parameters, one required, and a clear sibling relationship to ai_visibility_check.

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 documents all parameters. The description adds critical context: 'entities' must be 2-8 items, first is treated as the subject, and the other parameters (models, _apiKey, context) are explained with their roles. This significantly aids correct usage.

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 that the tool compares AI visibility across multiple entities side-by-side, probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It differentiates from siblings by specifying that it aggregates multiple probes into a comparative ranking.

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 the tool is useful for competitive AI-marketing audits and provides a concrete example question. However, it does not explicitly mention when to use this tool versus using ai_visibility_check alone for a single entity, leaving some inference 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 (readOnly, idempotent), the description explains composite behavior, potential latency (5-30s on first bundlephobia measurement), graceful degradation, and that sources_failed will list timeouts. No contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the main purpose. Every sentence adds value, though it could be slightly more concise. Still 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?

Comprehensive: covers return fields (summary, advisories, links, alternatives), edge cases (scoped packages), failure modes, and ecosystem scope. With no output schema, the description fully specifies expected 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 has 100% coverage with descriptions for package and version. The description adds useful context: scoped packages are accepted and version defaults to latest. This adds meaning beyond the schema field descriptions.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, covering license, advisories, bundle size, and tree-shaking. It distinguishes itself from siblings by focusing on npm packages and integrating multiple sources.

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 describes when to use (agent asks about safety/popularity/size) and when not to use (non-npm ecosystems, directing to deps.dev:version directly). Also mentions partial failures and how they are handled.

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

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

The description discloses key behavioral traits beyond annotations: no server-side search, fetches bulk data once, client-side filtering, case-insensitive matching, result capping. This fully informs the agent of the tool's operation 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 a single paragraph that packs all essential information efficiently. It front-loads the main purpose and uses parenthetical examples for clarity. Slight improvement could be breaking into sub-points, but it is concise and clear.

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

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

The description provides complete context for the tool's complexity: explains the data sources, search behavior, returned fields, and how the result ties to other tools. No output schema exists, but the description sufficiently covers what the agent needs to know.

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

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

The schema provides 100% coverage with parameter descriptions, but the description adds important context: name is case-insensitive and matched against both name and business name, limit defaults to 25 with a hard cap of 100, and status defaults to active. This enhances understanding beyond the schema.

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

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

The description clearly states the tool searches FARA registrants, defines what a registrant is, and distinguishes it from sibling tools like list_foreign_principals and get_registrant_documents by mentioning how the registration_number links to them.

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

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

The description explains when to use the tool (searching registrants by name substring), how to adjust status for active vs terminated, and hints at integration with other tools. It does not explicitly state when not to use it, but provides sufficient context for general usage.

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 false. The description adds beyond: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and returns offsets. 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 paragraph but well-structured with clear sentences. It front-loads the core purpose and usage, then adds technical details. Every sentence adds value, though it is a bit dense.

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 annotations, the description is complete. It explains return values (passages with offsets and scores), technical implementation, and pairing with sibling. No gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that 'text' is document content with max 200K chars, providing query examples, and noting default for limit. This goes beyond the schema descriptions.

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

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

The title 'Search Within a Source' and description clearly identify the tool's function: semantic search inside a fetched record. It specifies the verb 'search', the resource 'record', and distinguishes from siblings like 'ask_pipeworx_grounded' which is for grounded answers over passages, and 'search_registrants' which is entity search.

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

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

The description explicitly states when to use: when the record is too big for the prompt. It also explains pairing with 'ask_pipeworx_grounded' and gives query examples, effectively guiding the agent on context and alternatives.

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

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

Adds key behavioral details beyond annotations: returns subscription id, requires OAuth, phone verification, rate limits (10/day SMS), webhook auto-disable after 10 failures. No contradiction with annotations.

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

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

Well-structured with clear sections and examples. Slightly lengthy but every sentence adds value; front-loaded with main purpose. Minor room for tighter phrasing.

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 parameter types, delivery options, and constraints. Missing detailed return structure beyond 'returns subscription id', but acceptable for a creation tool without 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?

100% schema coverage; description enriches each parameter with practical examples and constraints, especially for nested delivery object (email, SMS, webhook with signing details). Adds significant meaning.

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

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

Clearly states it creates a subscription to a live-data event stream. Distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by detailing subscription types and delivery methods.

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

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

Provides explicit requirements (Pipeworx OAuth account), supported types with examples, delivery channel constraints, and verification steps. Lacks explicit when-not-to-use but context is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint = false, covering safety. The description adds behavioral context: it returns 'category-bucketed example questions...each with the exact tool + argument shape...drawn from the live catalog'. This is helpful but does not substantially expand beyond what annotations imply.

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

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

The description is somewhat long but well-structured. It front-loads alternative prompts (capturing user intent), then explains return values and usage modes. Every sentence adds value, though some redundancy exists (e.g., 'getting started' in the list is implied later). It could be slightly trimmed but remains 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?

No output schema exists, but the description adequately explains return values: 'category-bucketed example questions...each with the exact tool + argument shape'. It covers both call signatures (no args vs. topic), and is complete for a simple exploration tool. Slight gap: does not mention pagination or volume limits, but those are likely not needed.

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% (one optional parameter). The description adds significant meaning: it gives examples of acceptable values ('finance', 'pharma', 'betting') and explains the effect ('to focus'). This goes beyond the schema's minimal 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 defines the tool as an onboarding entry point that returns category-bucketed example questions. It uses specific verbs ('returns', 'call') and distinguishes itself from siblings by explaining it is the 'first' tool to use when unfamiliar with Pipeworx's capabilities.

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 this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and provides clear alternatives ('to learn how to call the meta-tools'). It also explains two modes: no arguments for full spread, or with topic for focus. It lacks explicit 'when not to use' but is very clear on 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?

The description adds important behavioral context beyond annotations: ownership enforcement and the fact that the row is deactivated, not deleted. Annotations already indicate non-destructive mutation, and description aligns and enriches.

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

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

Two sentences, no redundancy. The action is front-loaded and every sentence adds value.

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

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

For a simple tool with one parameter and annotations present, the description fully covers usage, ownership, and effects. No gaps.

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

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

Schema description coverage is 100% for the single parameter 'id', and the description does not add extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states the action 'Cancel a subscription by id', clearly defining the verb and resource. It differentiates from siblings like 'subscribe' and 'list_subscriptions' by specifying cancellation.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context but lacks explicit when-not-to-use or alternatives. It is still clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds rich behavioral context: it states the data sources (SEC EDGAR + XBRL), version (v1), the exact verdict values, and that it provides citations (pipeworx://). This goes well beyond annotations and fully discloses the tool's behavior.

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

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

The description is a single paragraph that front-loads with examples and usage guidance. It is dense but not excessively long. Every sentence adds value (examples, scope, output, efficiency claim). Could be slightly more structured (e.g., bullet list), but remains efficient 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 simplicity of the tool (1 parameter, no output schema, no nested objects), the description is complete: it defines scope, input format, output types, data sources, and when to use. No gaps are apparent for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100% (the single 'claim' parameter has a description). The tool description reinforces meaning by providing natural-language examples and clarifying input format. While baseline is 3 due to full schema coverage, the extra examples and context add value, raising the score by 1.

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 is natural-language claim verification against authoritative sources, specifically company-financial claims via SEC EDGAR+XBRL. It provides multiple example queries and explicitly lists the returned verdict types. The verb 'validate' combined with domain specification distinguishes it from siblings like 'deep_research' or 'resolve_entity'.

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

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

The description explicitly tells when to use ('Use whenever the agent needs to check whether something a user said is factually correct') and delimits the scope (company-financial claims for public US companies). It does not provide explicit when-not alternatives, but the context is clear enough for an agent to select appropriately among siblings.

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