Data Economie Fr

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds details about default model, BYO key for Anthropic, and return structure, providing valuable 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?

Single paragraph, front-loaded with purpose, then details. Efficient but could be slightly more structured with bullet points for clarity.

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

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

Given no output schema, description explains return structure (per-model score, confidence, signals, raw_response + combined view). Fully adequate for the tool's complexity.

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

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

Schema coverage is 100%. Description adds meaning: default model for 'models', BYO key for '_apiKey', and disambiguation for 'context'. Enhances 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?

Clearly states the tool probes LLMs for knowledge about entities and scores visibility. Differentiates from sibling tools like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on cross-model visibility scoring.

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?

Mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Implicitly shows when to use but lacks explicit exclusions or comparisons to 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?

The description adds value beyond annotations: annotations declare readOnlyHint=true and idempotentHint=true, but the description explains the routing behavior (5,564 tools, 1,462 sources) and what output to expect (structured answer with pipeworx:// citation URIs). It states 'one fast call' implying low latency. However, it does not mention rate limits, auth requirements, or what happens if no source matches. With annotations already covering safety (non-destructive, idempotent), the behavioral detail is good but not perfect.

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

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

The description is front-loaded with the key 'PREFER OVER WEB SEARCH' directive and a compact list of supported data types. It uses bold for emphasis and lists examples at the end. However, it is on the longer side for a description (roughly 100 words), and the later paragraph about when to use grounded/deep research could be slightly trimmed. Still, every sentence earns its place except perhaps the last note about 'what's the world saying' which is somewhat redundant.

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

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

Given the tool has no output schema, no nested objects, and 6 parameters with high schema coverage, the description does well to explain routing, citation output, and when to use alternatives. It explains the input parameter well. However, it does not describe the output format in detail (e.g., whether it returns JSON or text), nor does it mention pagination limits or error handling. For a tool this broad with many sibling tools, the completeness is high but not exhaustive.

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 schema already documents all 6 parameters (question and 5 aliases). The description adds meaning by explaining the parameter is 'Your question or request in natural language' and listing the aliases, but does not add syntax or format constraints beyond what the schema provides. The examples in the schema complement the description well. The baseline is 3 due to coverage, and the description earns +1 for the rich context about what kinds of questions work.

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-resource pairing: 'ask' + 'Pipeworx' and clearly states it routes questions to one of 5,564 tools across 1,462 verified sources, returning structured answers with citations. It explicitly distinguishes from the sibling ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad multi-part questions), and contrasts with web search by listing supported data categories like SEC filings, FDA drug data, and FRED statistics.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions — this is the default entry point'. It gives clear when-not-to-use guidance: use ask_pipeworx_grounded for hallucination-resistant answers with confidence, deep_research for broad multi-part queries, and web search is implied as fallback. It lists concrete query triggers like 'what is', 'look up', 'find', along with 11 diverse examples.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context: the experimental nature, that candidate improvements may be active live, current state (no candidate active, matches stable exactly), and that it is a full working router, not a fallback. No contradictions with annotations.

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

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

The description is concise (three sentences) and front-loaded with key identity and usage information. Every sentence adds value: beta identity, experimental nature, current state, usage guidance, and guarantee of full functionality. No wasted words.

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

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

Given the six parameters (all aliases), no output schema, and annotations covering safety, the description explains the tool's purpose, relationship to ask_pipeworx, current state, and usage context. It references 'same response shape' to cover return values. Sufficient for a beta tool, though a bit more detail about the response could elevate completeness.

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

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

Schema coverage is 100%, with all six parameters (aliases for question) fully documented in the schema. The description adds no additional parameter meaning beyond stating 'same arguments'. Baseline 3 is appropriate as the schema does the heavy lifting.

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 the beta version of ask_pipeworx, an identical universal router with the same tools and arguments. It distinguishes itself by indicating it carries candidate routing improvements and is the experimental edge, differentiating it from the stable ask_pipeworx sibling.

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

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

Explicitly tells the agent to use it exactly like ask_pipeworx when wanting the newest routing and notes that results are compared to the stable router. It implies the stable version is the alternative for stability, providing clear context on when to use this beta variant.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds significant behavioral detail beyond annotations: the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), the five possible refusal reasons, and the mechanism of extracting 'ONLY what the tool result contains'. The only minor gap is not explicitly stating that the tool may forward-fetch before extraction (implied by 'Same routing as ask_pipeworx'), but the cost mention compensates. 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 tightly written with no wasted sentences. The first sentence states the core value proposition ('Hallucination-resistant answer mode for high-stakes reads'). Every subsequent sentence adds distinct information: routing behavior, extraction mechanism, return structure, usage guidance, cost tradeoff, and examples. It uses front-loading and bullet-style formatting for the return types. Perfectly concise for the complexity offered.

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 (6 aliased parameters, no output schema, 33+ siblings, high-stakes use cases), the description is nearly complete. It explains what the tool does, when to use it, how it differs from siblings, what it returns on success and failure, and the cost. The only minor gap is that without an output schema, an agent might want more detail on how 'confidence' is calculated or what 'source' exactly contains, but the verbatim quote quote and fetched_at fields provide reasonable transparency. The refusal reasons list is particularly valuable.

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

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

Schema description coverage is 100% (all 6 parameters are aliases for 'question', each with a description). The description mentions 'Your question in natural language' which adds a usage hint beyond just the field name. However, the description does not add new semantic meaning beyond what the schema already provides; it just restates 'question' as the core input. Baseline 3 is appropriate for full schema coverage.

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

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

The description clearly states the tool provides a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb+resource ('extracts the answer using ONLY what the tool result contains'). It distinguishes itself from its sibling 'ask_pipeworx' by explaining the grounded extraction mechanism and refusal behavior, which is critical given the 33+ sibling tools.

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

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

The description explicitly tells when to use this tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and provides concrete high-stakes examples (financial verdicts, legal claims, medical lookups, public statements). It also explicitly tells when NOT to use it ('prefer ask_pipeworx for casual lookups') and explains the cost tradeoff ('Costs one extra LLM call vs ask_pipeworx'). This is exemplary.

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 extensive behavioral details: fan-out to multiple sources, resolver contract with confidence levels, safety mechanisms for low-confidence and closed markets, and cancellation rule parsing, far exceeding what annotations provide.

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

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

The description is verbose but well-structured with bold section headers (e.g., 'RESPONSE SHAPES', 'SAFETY') and front-loads the core purpose. Every section earns its place, though some details could be more terse for quicker agent parsing.

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

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

For a complex tool with no output schema, the description is remarkably complete: covers input variations, behavior, edge cases (closed markets, low confidence, wide spreads, cancellation rules), response structure, and safety, leaving no gaps.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant context: explains market parameter types (slug, URL, question text) and details the meaning of 'depth' and 'include_raw', enhancing the schema's minimal explanations.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question) and the tool's function, effectively distinguishing it from sibling tools like polymarket_edges or ask_pipeworx.

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 use cases are given: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' While it doesn't list alternatives, the context is clear and actionable.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral specifics: for company type, it pulls latest 10-K data with correct fiscal year handling; for drug type, pulls FAERS counts, FDA approvals, trial counts. Also explains result sorting by primary metric. 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 a single, well-organized paragraph. It front-loads with example queries and key instruction, then details for each type. While every sentence adds value, slight conciseness improvement (e.g., splitting into shorter sentences) could be made.

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 fully covers what the tool does, how to use it, data sources for each type, result ordering, and output format (paired data + citation URIs). No missing context given the tool's complexity and absence of 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% (2 parameters fully described). The description enriches parameter meaning: explains that 'type' determines data source (company vs drug) and 'values' expects tickers/CIKs or drug names with examples. This exceeds schema documentation.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides specific verb-resource pairs (compare X and Y, rank these companies) and distinguishes from sequential lookups, fully differentiating from 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and gives clear when-to-use scenarios (comparison queries like 'which is bigger'). Provides examples of natural language triggers, making usage unambiguous.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds value by specifying returned metadata (fields/schema, themes, record count) 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?

Single sentence efficiently conveys purpose, target dataset, and usage recommendation with no 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 info tool with one parameter and good annotations, the description adequately covers what the tool does, what it returns, and when to use it, meeting the context's needs.

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

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

Schema coverage is 100% with parameter description 'Dataset id from search_datasets.' Description does not add additional meaning beyond the schema, so baseline score applies.

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

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

The description clearly states the tool gets metadata for one France Economy & Finance Open Data dataset, specifying fields/schema, themes, and record count. It distinguishes the tool from siblings like search_datasets by focusing on individual dataset metadata.

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

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

Explicitly advises calling before a query to learn column names, providing clear context for when to use. However, does not mention alternatives or when not to use, slightly reducing specificity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds substantial behavioral context beyond annotations: account requirement, data source scope (not open-web), parallel routing, findings packet with gaps[], contradictions[], hop field, citation_uri, semantic excerpting of large records, and expected timing (15-90s). It also cautions that deep_research on current news returns mostly empty gaps. 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 relatively long but every sentence earns its place by providing essential operational detail (account, depth options, data source type, expected output format, timing, limitations). It front-loads the critical 'ACCOUNT REQUIRED' and fallback tool. Could be slightly reorganized for scanability but remains well-structured and information-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?

With 2 parameters, no output schema, and exhaustive parameter descriptions, the description covers all key aspects: what returns (findings packet with evidence, gaps, contradictions), timing, depth behavior, data source distinction, and limitations for current news. Minor omission: no explicit mention of rate limits or pagination, but given the single-call nature and 15-90s timing, this is acceptable.

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

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

Schema description coverage is 100% (both parameters documented). The description goes beyond schema by explaining the behavioral impact of each depth option ('quick'=single hop, 'standard'=gap recovery+contradictions, 'thorough'=paid, adds iterative hop+contradictions). The question parameter is correctly described as natural language for broad/multi-part queries. This adds significant meaning beyond the schema's enum labels.

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

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

The description clearly states the tool performs 'grounded multi-source research' across Pipeworx's 1462 structured data sources using parallel decomposition. It specifies the exact verb ('research') and resource (structured data sources, not open web), and distinguishes it from siblings like ask_pipeworx (for single lookups) and for breaking news. The scope is precise: broad/multi-part questions over 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 provides when-to-use (broad/multi-part questions over structured data) and when-not-to-use (breaking/colloquial current news, prefer ask_pipeworx). Identifies a fallback tool (ask_pipeworx if not signed in). Also notes account prerequisite and paid tier for 'thorough' depth. No ambiguity about alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds important behavioral details: returns top-N most relevant tools with names, descriptions, and full input schemas (with curated examples), and each result is ready to call directly without a second schema lookup. No contradiction with annotations.

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

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

The description is well-structured: purpose first, then domain list, then return format, then usage hint. Every sentence adds value, though it could be slightly more concise. Clear and front-loaded.

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

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

Given the tool's purpose (discovery among many domains and many sibling tools), the description is complete. It explains what results contain, that they are call-ready, and provides usage context. No output schema needed as return behavior is described sufficiently.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds examples ('analyze housing market trends') and mentions limit defaults, but this largely repeats schema info. Baseline 3 for high coverage; description adds minimal extra meaning.

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

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

The description clearly states 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings like 'search_datasets' or 'query' by being a tool discovery mechanism.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use and implies when not to (if you already know the tool).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context beyond these: the tool fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), describes the exact return fields (cik, company_name, recent_filings, fundamentals, patents with sunset caveat, news via fallback, LEI), and notes soft-failure for patents. 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 front-loaded with example queries and a clear purpose statement. While it is long (several lines), each sentence serves a purpose: explaining return fields, fallback behavior, and usage constraints. A minor improvement would be to trim redundancy (e.g., repeating 'names not supported' twice), but overall it is well-organized and efficient for the tool's complexity.

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

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

There is no output schema, so the description must explain return values. It lists all returned fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents with sunset date, news via fallback, LEI). It also covers input constraints (only ticker/CIK, not names) and provides a fallback alternative (resolve_entity). For a multi-source aggregation tool, 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?

Input schema has 100% description coverage. The description adds essential meaning: it explains the type parameter is limited to 'company' (others coming soon), and the value parameter accepts ticker or zero-padded CIK but not names, reinforcing the schema's note. It also directs to resolve_entity for names, which is not in the schema. This adds value beyond the structured fields.

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 clear example queries ('Tell me about X', 'research Acme') and states the tool produces a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from siblings like resolve_entity by specifying that names are not supported. The verb 'profile' and resource 'US public company' are explicit.

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 to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides clear exclusion criteria: 'names not supported (use resolve_entity first if you only have a name).' This gives both when-to-use and when-not-to-use guidance with a named alternative.

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 destructiveHint=true and idempotentHint=true; description adds context about clearing sensitive data, which is helpful beyond annotations.

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

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

Two concise sentences that convey all necessary information without waste.

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

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

For a simple, single-parameter tool with no output schema, the description is fully complete given low complexity.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter; description does not add significant additional meaning beyond the schema.

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

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

Clearly states 'Delete a previously stored memory by key' with specific verb and resource, and distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data' and mentions pairing with 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 indicate read-only, idempotent, non-destructive. The description adds that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond annotations by explaining the fetch and extraction behavior, but does not disclose potential rate limits 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 four sentences, front-loaded with purpose and process, followed by output format and use cases. No redundant information; 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 no output schema, the description explains the output is a single text blob ready to drop at site-root/llms.txt. It covers the fetch, extraction, and output process. The tool is simple with two parameters, and the description fully equips an agent to use it 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 description coverage is 100%. The description adds minimal extra meaning beyond the schema, such as explaining that 'key links' are extracted for the 'url' parameter. For 'max_links', the schema already states default and max values. Overall, the description provides marginal added 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 generates a production-ready llms.txt file for any URL. It specifies the verb 'generate' and the resource 'llms.txt file', and distinguishes itself by mentioning use cases like getting indexed or auditing competitors, which differentiates it from sibling 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 lists explicit use cases: getting a client's site indexed, drafting for your own project, auditing competitors. It provides clear context but does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds return fields and scope, aligning well 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?

Two clear sentences front-loading purpose and usage, with no waste.

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?

All needed info present: caller scope, return fields, single parameter. No output schema needed as fields are enumerated.

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; the description does not add extra meaning beyond the parameter description already in the schema.

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

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

Explicitly states it lists the caller's active subscriptions and enumerates return fields. Distinguishes 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?

Clear guidance: use to review monitors before adding more or to find an id to cancel. Implicitly contrasts with adding/modifying 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?

With all annotations false, the description carries the full burden. It discloses the claim_token return-and-pass-back workflow, rate limit of 5 per identifier per day, free/quota-exempt status, and daily digest handling. These are meaningful behavioral traits beyond the schema.

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 every sentence contributes: purpose, usage, exclusions, content guidance, token workflow, rate limit, and cost. It is front-loaded and organized, with no filler.

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

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

For a feedback tool with an optional nested context param and no output schema, the description explains the follow-up mechanism and expected return token, covers rate limiting and server boundaries, and gives content instructions. This makes it fully usable without additional documentation.

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 applies. Description enriches claim_token by explaining the round-trip read workflow with a concrete example, and message by instructing specificity and forbidding pasting prompts. This adds value beyond the schema, though not maximally for all params.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates exact feedback types (bug, feature, data_gap, praise) and explicitly scopes to Pipeworx tools, distinguishing it from sibling tools like ask_pipeworx or query which are for information retrieval, not feedback.

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

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

It provides explicit 'Use when' criteria for bug, feature, data_gap, and praise, and explicit 'ONLY for tools served by this Pipeworx connection' exclusion with redirection to other servers as an alternative. It also tells users what not to include (end-user prompts). This is exemplary usage guidance.

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

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

Adds caching behavior (5min-1h), states no PII, and explains data source (CF analytics-engine). Annotations already provide readOnly, openWorld, idempotent, non-destructive hints. 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?

Well-structured, front-loaded with core functionality. Three sentences plus bullet list; every sentence adds value. Slight verbosity but acceptable.

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 values (top tools, packs, volume) despite no output schema. Tool is simple, no missing context. Adequate for a read-only, cached trend 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?

Parameter `window` has full schema coverage with enum values described. Description adds context: shorter windows for hot right now, longer for steady-state, enriching 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 the tool returns trending data (top tools, packs, call volume) based on recent window. Distinguishes from siblings like ask_pipeworx or discover_tools by focusing on popularity signal.

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?

Lists three specific use cases explicitly, providing guidance on when to use. Does not explicitly mention when not to use or alternatives, but context implied by 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond these, detailing internal logic (Jaccard similarity ≥0.3, partition filter dropping placeholder slugs, fill check against live CLOB depth) and output structure. 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 relatively long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though some parts could be slightly tighter without losing clarity. The core purpose is front-loaded.

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

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

For a tool with 2 optional parameters and no output schema, the description comprehensively covers behavior, output format (opportunities array, partition_check), edge cases (placeholder slugs, low similarity), and integration with sibling tools. This makes the tool fully understandable without external documentation.

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 event and topic. The description enriches these by explaining the exact usage (e.g., full URLs accepted for event, seed questions for topic), the underlying algorithms (monotonicity checks, partition-sum), and the output consequences. This adds significant 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 opens with a clear statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It further distinguishes the three modes (no args, event, topic) with precise use cases, and differentiates from sibling tools like polymarket_fill_risk by referencing it for custom sizing.

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 each parameter: event for a specific market slug/URL, topic for cross-event scanning. It also provides a negative case: 'do not trade it' when realizable_edge_pp ≤ 0, and recommends polymarket_fill_risk for custom sizing. This gives clear decision 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 mark the tool as read-only and idempotent. The description adds extensive behavioral details: explains model formulas (FRED log-returns, GDELT ratios), partition overround with per-sport alpha, placeholder filtering, edge calculation net of slippage, Kelly cap at 0.25, 24h-move warnings, caching behavior, and diagnostic counters. 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 long and includes detailed model formulas that could be in separate documentation. However, it is well-structured with clear sections (segments, response fields, knobs) and front-loads the purpose. It could be more concise but remains informative.

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 9 parameters, no output schema, and rich annotations, the description covers all aspects: returns, segments, diagnostics, caching, edge cases (Fed bets), and filtering knobs. It leaves little ambiguity about the tool's behavior 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% so parameters are documented. The description adds value by explaining nuances like slippage_pp (zero fees but thin depth) and min_partition_leg_kelly (why min_kelly doesn't filter partitions). Not every parameter gets extra context, but the additions are helpful.

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 scans Polymarket for opportunities where Pipeworx data disagrees with market price. It specifies three segments (model-driven, structural arbitrage, concentrated longshot) with detailed model descriptions, making the purpose very specific and distinct from 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 explains this is for discovering betting opportunities without paging markets, and mentions Fed bets as an excluded special case with a rationale. It provides context on how to use knobs like min_liquidity and max_spread_pp, but lacks explicit comparison to sibling tools or when-not-to-use scenarios.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral context: it reads from daily snapshots, returns three structured arrays (tracked, expired, snapshot_dates), explains that gaps occur due to cache-miss conditions, and notes that decay numbers are based on daily closes not intraday. 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 fairly long but front-loaded with the core question. It is well-structured, starting with the main purpose, then explaining the response fields, and ending with limits. Every sentence provides meaningful information; 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?

There is no output schema, but the description thoroughly explains the return structure: tracked[] with time-series, first_seen, trend, decay; expired[] with lifespan_days; snapshot_dates[]. It also covers limitations (60-day TTL, gaps, decay calculation). For a tool of this complexity, it is remarkably 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%, baseline 3. The description adds value by explaining 'days' as lookback with default 14 and max 30 (schema says clamp 2-30), and 'window' as snapshot family with default '1wk'. It also clarifies concepts like snapshot family and how they affect the data, which is not in the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and differentiates itself from the sibling tool 'polymarket_edges' by focusing on historical evolution rather than current edges only.

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 explains when to use this tool (to understand edge persistence and decay) and provides a rationale distinguishing fresh vs. old edges. It does not explicitly name alternative tools but implies that for current edges only, one should use polymarket_edges. Limits like 60-day TTL are also mentioned.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate a safe, read-only operation. The description adds significant behavioral context: walks the ladder, returns detailed metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and flags forced directional risk. 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 sections for SINGLE-MARKET and BASKET, front-loading the core purpose. Every sentence adds information, though minor redundancy (e.g., repeating 'default 1000') could be trimmed for greater conciseness.

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

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

Given the tool's complexity (two modes, many return fields) and no output schema, the description is comprehensive. It lists all return values (top_of_book, vwap_fill_price, etc.), explains basket-specific outputs (capture_ratio, thin_legs, forced_directional_risk), and warns about risks, making it complete for an AI agent to understand 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining mode-specific behaviors (e.g., default 'auto' for side in basket mode, interpretation of size_usd for buys vs sells). It clarifies how parameters interact with the tool's logic 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying its role as a pre-trade validation step.

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

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

Explicitly advises to use this tool before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above $500. Warns about partial basket fills converting arb into unhedged directional position, providing clear when-to-use and when-not-to guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond these: details on compatibility_warning cases (non-equivalent bet shapes, semantically unrelated events), temporal alignment implications, and skipped cross-type/subtype counters. No contradiction with annotations.

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

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

The description is well-structured with sections and front-loaded purpose, but it is verbose. Some detailed explanations (e.g., skipped counters) could be simplified without losing essential guidance. It earns its place but could be 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 3 parameters, no output schema, and high complexity (cross-venue, compatibility, temporal alignment), the description thoroughly covers all aspects: modes, response fields, safety fields, interpretation of warnings, and limitations. An agent can fully understand how to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics: explains the override behavior of explicit tickers over topic, provides the list of 10 topic shortcuts with examples ('fed', 'btc'), and clarifies that topic is optional. 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 a specific verb-resource combination: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison rather than intra-venue edges. The two modes (topic vs explicit) are well-defined.

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 context for when to use the tool (comparing same question across venues) and when not (compatibility warnings, temporal misalignment). It warns that most pre-mapped topics return warnings, helping the agent set expectations. While it doesn't name alternative tools explicitly, the context is strong enough to guide usage decisions.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description adds that it uses ODSQL for the operations, which is useful context. 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?

One sentence, approximately 25 words, front-loaded with action and resource. Parenthetical list efficiently enumerates capabilities. No superfluous content.

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

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

Description covers the main purpose and capabilities. Given the presence of annotations and full schema coverage, it is sufficiently complete despite lacking output schema or error handling details.

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% description coverage and includes examples. Description summarizes the operations (where, group_by, etc.) but does not add significant meaning beyond the schema. Baseline of 3 is appropriate.

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

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

Description clearly states verb and resource: 'Query records from a France Economy & Finance Open Data dataset with ODSQL.' It lists distinct operations (filter, aggregate, sort, paginate) and distinguishes from siblings like search_datasets which searches for datasets.

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

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

Description implies usage context (querying France Economy & Finance data via ODSQL) but does not explicitly state when to use or avoid this tool relative to siblings. No exclusions or alternative tools are mentioned.

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

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

Annotations already provide read-only and idempotent hints. Description adds valuable behavioral context: scoping by identifier (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, which aids agent understanding.

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?

Concise three-sentence description with front-loaded action ('Retrieve a value...'). Every sentence adds value; no wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers retrieval behavior, listing behavior, scoping, and tool pairing, making it complete for agent use.

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

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

Schema has 100% coverage with description for 'key'. Description adds context: 'omit to list all keys' and provides examples, enhancing understanding beyond schema.

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

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

Clearly states verb 'Retrieve' and resource 'value saved via remember' and provides alternative behavior (list keys). Distinguishes from sibling tools 'remember' and 'forget' by 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?

Explicitly describes when to use: 'look up context...without re-deriving it from scratch.' Mentions scoping and pairing with remember/forget, but does not explicitly state when not to use it.

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

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

The description claims mark_read:true modifies read status, contradicting the readOnlyHint=true annotation which asserts read-only behavior. This is a serious inconsistency.

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?

Very concise, front-loaded with purpose, every sentence adds value. No 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?

Despite lacking an output schema, the description thoroughly explains return fields (source, citation_uri, raw payload) and usage patterns (filtering, polling, alternative URL). Complete for a read-oriented tool.

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

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

The description adds context beyond the schema, especially for mark_read (state change) and the polling hint. With 100% schema coverage, baseline is 3, but the extra context earns a 4.

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 pulls fired events from a subscription feed, specifies what each event carries, and distinguishes it implicitly from sibling tools that manage 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 explains filtering by type and since, how mark_read works, and mentions polling suitability and an alternative access URL. It lacks explicit when-not-to-use or comparisons to 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?

Beyond annotations (read-only, idempotent), the description details the fan-out to multiple sources, the fallback mechanism (GDELT→GNews), the USPTO soft-fail status, and the return format including citation URIs.

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 information-dense but remains readable and front-loaded with example queries. A more structured format (e.g., bullets) could improve clarity further.

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

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

Despite lacking an output schema, the description adequately explains the return structure (changes grouped by source, total_changes count, citation URIs) and covers edge cases like soft-failures. Fully sufficient for an agent to understand the tool.

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

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

Schema coverage is 100%, and the description adds value by explaining the 'since' format with examples and the overall behavior, though more detail on the 'value' parameter could be given.

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 a change feed for a company in a recent window, with explicit examples of user queries. It distinguishes from the sibling tool 'entity_profile' by noting the static vs. temporal scope.

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

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

Provides explicit guidance on when to use this tool versus 'entity_profile', and offers example queries and suggested values for the 'since' parameter (e.g., '30d').

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 it as idempotent and not destructive. Description adds behavioral details: scoped by identifier, authenticated users persistent, anonymous 24h retention. No contradiction with annotations.

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

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

Four sentences, each serving a distinct purpose: general function, usage advice, storage details, companion tools. No wasted words, front-loaded.

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

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

No output schema, but description explains persistence behavior, scoping, and retention. Covers what the agent needs to know for a write tool, though lacks details on error handling or performance.

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

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

Schema covers both parameters with descriptions (100% coverage). Description provides examples of key naming patterns but doesn't add meaning beyond schema.

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

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

The description explicitly states the tool saves data for reuse across sessions, with concrete examples (ticker, address, preference). It distinguishes from siblings recall and forget, which are mentioned as related tools.

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

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

Clearly advises use when discovering something worth carrying forward, and pairs with recall and forget for retrieval and deletion. Provides explicit context on when 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses identifier source-labeling, explicit `unresolved` reporting, graceful degradation when GLEIF/OpenFIGI are unavailable, and internal cascading lookups. This rich behavioral context exceeds what annotations alone provide, with 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 verbose, opening with a long list of example queries before the core purpose statement. While structured with 'SUPPORTED TYPES' and detailed subsections, it could be tightened to improve front-loading without losing key information.

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

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

Given the tool's complexity and lack of an output schema, the description covers all essential aspects: supported types, output identifiers (CIK, ticker, LEI, FIGI, RxCUI), ownership data, unresolved handling, internal processes, and graceful degradation. It is fully self-contained for an agent to invoke correctly.

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

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

The schema already covers both parameters at 100% coverage. The description adds valuable semantics like accepting ISIN as input, explaining the ISIN-to-LEI mapping, and distinguishing behavior by entity type. Some information is redundant with the schema, but the additional layer of meaning justifies a 4.

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 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and provides concrete query examples. It clearly distinguishes from siblings like compare_entities and entity_profile, which serve different purposes (comparison and profiling).

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID' and notes that it replaces 2-3 manual lookups, giving clear when-to-use context. However, it does not explicitly name alternative tools or when-not-to-use cases, so it falls short of the top score.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds value by explaining the tool probes each entity, ranks by score, and surfaces most/least recognized. It also describes the output (ranked list with score, confidence, signal density). 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?

Description is concise (three sentences) with no wasted words. Front-loaded with purpose and action. Each sentence adds value: purpose, mechanism, use case, output.

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 rich annotations and full schema coverage, description is complete. It explains return values (ranked list) despite no output schema. Covers all necessary aspects for the agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add significant meaning beyond schema; it rephrases parameter descriptions (e.g., 'entities' as brand names) and provides a usage example, but does not add new constraints or format details.

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

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

Description clearly states the verb 'compare' and resource 'AI visibility' across multiple entities. It explains the process of probing each entity with ai_visibility_check and ranking results. The purpose is well-distinguished from sibling tool ai_visibility_check, which is for single entities.

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

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

Description explicitly states 'Useful for competitive AI-marketing audits' and provides a concrete example. It implies when to use (comparing multiple entities) but does not explicitly mention when not to use or alternatives. The context is clear enough for 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds valuable context: partial failure handling, bundlephobia timing delay, and that failed sources are listed. 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 purpose. Each sentence adds value, though slightly lengthy. Could be trimmed without loss of key information.

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

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

Despite no output schema, the description thoroughly explains return structure (summary block, per-advisory detail, links, alternatives), partial failure behavior, and ecosystem scope. Complete 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?

Schema coverage is 100%; description adds minor value by noting scoped package acceptance for 'package' and confirms default behavior for 'version'. Does not substantially extend schema documentation.

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

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

The description clearly states the tool does a composite check for npm package viability, covering license, advisories, bundle size, etc. It distinguishes itself by specifying NPM ecosystem only, contrasting with other tools for different ecosystems.

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

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

Explicit use cases are given: when asked 'is X safe/popular/small' or 'what does adding lodash cost'. It also states ecosystem limitation (NPM only), implying not to use for other ecosystems. However, it does not list specific sibling tools as alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds domain specificity (France Economy & Finance) and return fields, which supplements the annotations without contradicting them. It provides useful context beyond the safety profile.

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

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

The description is two sentences, front-loading the core purpose and immediately following with return values and usage guidance. Every word adds value with no redundancy.

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

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

Despite no output schema, the description fully explains return values (dataset_ids, titles, themes, record counts) and suggests next steps. Parameters are fully documented in schema, and the domain is clearly specified. Complete for a search tool.

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

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

Schema coverage is 100%, so all parameters are described in the schema. The description does not add extra meaning beyond the schema; it only restates that search is by keyword. 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 specifies the verb 'Search' and the resource 'France Economy & Finance Open Data for datasets', with specific keyword domains. It also states the return values (dataset_ids, titles, themes, record counts) and explicitly mentions passing dataset_ids to sibling tools (query/dataset_info), distinguishing it from those tools.

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

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

The description implies a workflow by stating 'Returns dataset_ids (pass to query/dataset_info)', which guides use as an initial search step. However, it does not explicitly mention when not to use this tool or provide alternatives among siblings, so it is clear but lacks exclusions.

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

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

Adds significant behavioral context beyond annotations: embedding model (BGE-base-en), windowing (500-char overlapping), similarity metric (cosine), character cap (200K chars with truncation flag), and return details (passages with offsets and similarity scores). 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?

Description is concise (3 sentences) with no extraneous information. Key information is front-loaded: purpose, when to use, and technical details follow logically.

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

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

Despite lacking an output schema, description fully explains return values (passages with character offsets and similarity scores) and limitations (200K char cap). The embedding methodology and pairing advice complete the context for effective use.

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

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

Schema coverage is 100%, so baseline is 3. Description reinforces schema but adds example queries for 'query' parameter and specifies default value for 'limit.' The added examples improve usability beyond schema alone.

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

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

Description clearly states 'Semantic search INSIDE a fetched record,' specifies verb (search), resource (record text), and scope (inside a fetched record). Distinguishes from siblings by mentioning pairing with 'ask_pipeworx_grounded' and context of large records.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides alternative 'Pairs with ask_pipeworx_grounded.' Also explains how it saves context and returns only relevant passages.

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 states 'Create a proactive monitoring subscription... Returns the new subscription id,' which implies each call creates a distinct new subscription (non-idempotent behavior). However, the annotations declare idempotentHint=true, indicating the tool is designed to be idempotent (multiple identical calls should have the same effect). This contradiction is critical: the description's claim of returning a 'new' id directly conflicts with the annotation's idempotency hint, thereby misleading the agent about the tool's actual 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 well-structured and efficient. It opens with a concise one-sentence summary, then logically groups types and delivery channels with bullet-like examples. Every sentence adds value—no filler. It front-loads the main purpose and critical constraints (e.g., OAuth requirement, phone verification). The length is appropriate for the complexity of the tool.

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

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

Given the non-trivial complexity (3 parameters, nested objects, multiple type variants, and no output schema), the description is remarkably complete. It covers input semantics, authentication prerequisites, delivery channel behavior (always-on feed, optional email/SMS/webhook with constraints and rate limits), and even webhook security details (HMAC signing). The return value (subscription id) is stated. No obvious gaps remain for an agent to invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds substantial context beyond the schema. It explains each 'type' enum value with concrete examples (e.g., polylarket_edge with params:{topic:'fed'}) and details the 'params' object structure per type. It also enriches the 'delivery' object with constraints (phone verification, 10 SMS/day cap, webhook signing). This extra information is essential for correct invocation, far exceeding the schema's basic descriptions.

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly specifies the verb (Create) and the resource (subscription to alerts), making the purpose immediately obvious. It also lists supported types and delivery channels, further clarifying the scope. Although it doesn't explicitly distinguish from siblings like 'list_subscriptions' or 'unsubscribe', the purpose is unambiguous.

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

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

The description provides clear context: it requires a Pipeworx OAuth account and explains that anonymous and BYO cannot persist subscriptions. It also describes when each subscription type is appropriate (e.g., 'sec_8k for 8-K filings matching ticker + item codes'). However, it does not explicitly state when to use this tool versus alternatives like 'list_subscriptions' or 'unsubscribe', though the context implies creation.

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 context about output structure (categories with tool+argument shapes) and that it draws from a live catalog, which is useful for understanding behavior 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?

While longer than minimal, the description is well-structured: starts with common user queries, then describes functionality, usage, and output. Every sentence serves a purpose without redundancy.

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

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

Given no output schema, the description adequately covers return content (categories of example questions). It also explains the tool's role in onboarding. Slightly more detail on the exact structure of examples could improve completeness, but it remains informative.

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 the single 'topic' parameter already described. The description reinforces this with concrete examples and explains the effect of omission (full spread), adding value beyond the schema.

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

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

The description clearly states this is the onboarding entry point that returns category-bucketed example questions with tool paths. It distinguishes itself from sibling meta-tools like ask_pipeworx and discover_tools by explicitly recommending use 'FIRST when you do not yet know what Pipeworx can do'.

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

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

Explicitly advises using this tool first for discovery and to learn meta-tools. Mentions optional topic parameter to narrow focus. While not listing when-not-to-use exhaustively, the context clearly differentiates it from other query 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?

Discloses ownership enforcement, deactivation vs deletion, and historical data preservation via recent_alerts. All behaviors are consistent with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), adding value beyond structured fields.

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, 33 words, front-loaded with primary action. Every sentence adds essential information: action, ownership constraint, and side effects. 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?

Completely describes the tool's purpose, constraints, and effects for a simple tool with one parameter and no output schema. The description is sufficient for correct selection and invocation.

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

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

Schema coverage is 100% (id described as 'Subscription id (uuid) returned by subscribe'). The description adds minimal extra meaning by referencing 'subscribe', but baseline of 3 is appropriate since schema already fully documents the parameter.

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

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

The description clearly states 'Cancel a subscription by id', specifying the verb and resource. It distinguishes itself from sibling tools like 'subscribe' (creates) and 'list_subscriptions' (lists), and adds ownership enforcement.

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 clear context: ownership enforcement means only the owner should use it. Mentions that rows are deactivated, not deleted, directing users to recent_alerts for history. Lacks explicit when-not-to-use or alternatives.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses crucial behavioral details: return verdict values, the distinction between 'could_not_verify' (check didn't happen) and 'unsupported' (no source covers it), the presence of verification_error, and the pipeline behavior (routed, verbatim evidence, then judged). It also mentions citation format (pipeworx://). 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 long but densely packed with necessary information: trigger phrases, use case, routing, return value semantics, and error handling. It is front-loaded with use triggers, but the middle section becomes a wall of text. While every sentence is informative, it could be better structured with bullet points or split paragraphs. Still, it remains appropriately sized for a complex tool.

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

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

The tool has no output schema, so the description must fully explain return values, which it does: verdict values, actual value with citation, and reasoning. It also covers failure modes (could_not_verify with verification_error, unsupported), routing logic, and the fact that it replaces multiple sequential calls. This is complete for an agent to select and invoke the tool correctly, and enough to interpret the result.

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

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

Schema coverage is 100%, but the description adds meaningful semantics beyond the schema. For 'claim', it provides concrete examples ('Apple's FY2024 revenue was $400 billion'). For 'tolerance_pct', it explains how it overrides implied wording, suggests values for hallucination detection (1–2), and states the default/cap (implied by wording, capped at 5). This goes well beyond the schema's bare 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 is highly specific: it defines the tool as natural-language claim verification with explicit trigger phrases ('Is it true that…', 'fact check', etc.). It clearly differentiates from siblings by stating it 'Replaces 4–6 sequential calls' and distinguishing between company-financial claims (SEC EDGAR fast path) and any other factual claim (grounded pipeline).

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance (financial vs other claims) and notes that the tool replaces multiple sequential operations, implying it should be chosen over manually chaining lookup/comparison tools. No explicit exclusions, but the scope is well-defined.

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