Mastodon

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds valuable behavioral context: default model is Workers AI Llama (free), BYO key for Anthropic, and per-model return structure (score, confidence, signals, raw_response) plus combined view. No contradictions.

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

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

The description is concise and well-structured: one sentence for purpose, one for defaults and optional parameters, one for return format, and one for use cases. No redundant or wasted words.

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

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

Given no output schema, the description adequately explains the return format (per-model and combined view). All 4 parameters are covered, and the use cases are clear. No additional context needed for a tool of this complexity.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds meaning beyond schema by explaining default model behavior (workers-ai used by default), when to provide `_apiKey` (if 'anthropic' in models), and the purpose of `context` (disambiguation).

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: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility (0-100). It uses specific verbs ('probe', 'score') and distinguishes itself from sibling tools by focusing on multi-model AI visibility audits.

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

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

The description explains when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and how to use optional parameters like `_apiKey` for Anthropic probes. However, it does not explicitly state when not to use it or name alternatives among siblings, leaving some implicit 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 readOnly, openWorld, idempotent hints, and non-destructive. The description adds valuable behavioral context beyond annotations: it routes internally, fills arguments, returns stable pipeworx:// citation URIs, and works 'on every tier, one fast call'. This enriches the agent's understanding of what to expect.

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?

Although the description is long, every sentence carries essential guidance. It is front-loaded with the key directive ('PREFER OVER WEB SEARCH'), then methodically covers domains, mechanics, triggers, examples, and escalation paths. No filler or redundancy detected.

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

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

Given the absence of an output schema, the description compensates by explaining the return format (structured answer with pipeworx:// citation URIs). It covers what the tool does, when to use it, how it routes, and how it differs from alternatives. The complexity of a meta-router tool is fully addressed within the description.

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 six parameters are aliases for 'question' with a clear description and examples). The tool description adds no further parameter-level detail; it only reinforces the natural-language prompt advice. Per the baseline rule for high schema coverage, a score 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?

The description clearly states that ask_pipeworx routes factual questions to the appropriate tool among 5,529 tools across 1,455 verified sources and returns structured answers with citations. It distinguishes itself from siblings by being the default entry point and by explicitly naming alternatives like ask_pipeworx_grounded and deep_research.

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', 'START HERE for most questions', and step-up instructions for grounded (hallucination-resistant) or deep_research (broad/multi-part) use. It also lists trigger phrases and examples, making it unambiguous when this tool should be selected.

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' read-only/idempotent hints, the description adds crucial behavioral context: this is an experimental edge with candidate routing improvements enabled live when under test, currently matches ask_pipeworx exactly, and 'falls back to nothing'—meaning it is a fully functional router. This clarifies that its behavior may shift over time and that results feed into merge decisions, which annotations alone cannot convey.

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

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

The description is structured with four sentences, each serving a purpose: identifying the beta, explaining current state, giving usage, and reassuring it is a full router. It is slightly longer than necessary but front-loaded with the core identity and maintains relevance throughout.

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

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

For a tool with no output schema, the description covers its experimental nature, relationship to the stable router, and current equivalence. It references ask_pipeworx for exact behavior, which is sufficient given the tool's complexity and the presence of a documented sibling. The main omission is a more detailed explanation of what 'universal router' means operationally, but the description is otherwise 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?

The input schema already documents the `question` parameter and all aliases with 100% coverage, so the baseline is 3. The description only repeats that it takes 'the same arguments' as ask_pipeworx, adding no semantic detail beyond what the schema already provides.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and response shape. It distinguishes itself from the stable ask_pipeworx by noting it may have candidate routing improvements enabled, and clarifies it is a full working router. The specific verb 'routing' and resource 'ask_pipeworx' make the purpose unambiguous.

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

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

The description explicitly advises to use it exactly like ask_pipeworx when wanting the newest routing, giving a clear when-to-use condition. It also explains that results are compared against the stable router to decide what merges, implying its experimental evaluation purpose. However, it does not explicitly state when to avoid it in favor of the stable router, so it lacks a full exclusion.

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?

Despite annotations already indicating readOnly and idempotent, the description adds rich behavioral detail: it uses ONLY the tool result, returns a structured response with evidence and confidence, enumerates specific refusal reasons, and discloses the extra LLM call cost. This goes well beyond the annotations and provides no contradiction.

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

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

The description is front-loaded with 'Hallucination-resistant answer mode' and packs routing, return format, usage, and cost into two long but information-dense sentences. Every clause serves a purpose, with no redundant filler.

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

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

Given the tool's complexity and lack of an output schema, the description compensates by detailing the exact success and refusal JSON structures, refusal reason enums, use cases, and cost trade-off. It is complete for a high-stakes grounded Q&A tool with strong annotations.

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 being aliases for 'question,' and the schema fully documents them. The description does not add parameter-specific detail, but the schema already defines the natural language question parameter and aliases, so baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and clearly explains it routes like ask_pipeworx but extracts answers only from tool results. It distinguishes itself from siblings like ask_pipeworx by detailing the refusal behavior and return structure, making the purpose unmistakable.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and it names the alternative 'prefer ask_pipeworx for casual lookups.' This gives clear when-to-use and when-not-to-use criteria with a specific sibling 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?

The description extensively details behavior: market resolution, classification, fan-out, evidence packet, match confidence, parent event extraction, news fallback, safety short-circuits, and resolution rules. 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 well-structured with clear sections and front-loaded purpose. Each part adds necessary detail for a complex tool; minor verbosity is justified.

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 and three params, the description covers all behavioral aspects: fan-out, response shapes, edge cases (low confidence, closed markets, wide spreads), and resolution risk. Completely adequate.

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

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

Schema covers all 3 parameters with descriptions. The description adds value by illustrating input formats (slug, URL, question text), depth options (quick/thorough), and include_raw trade-offs. While schema is complete, description enriches understanding.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call, specifying inputs like slug, URL, or question text. It distinguishes itself from siblings by its specialized focus on Polymarket and 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?

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides examples of fan-outs and classifiers, guiding when to invoke 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals crucial behavioral details: it performs parallel data retrieval, pulls specific financial metrics from SEC EDGAR/XBRL for companies and FAERS data for drugs, sorts results by primary metric, and returns citation URIs. It also explains handling of different fiscal year ends, which is not obvious from 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 and front-loaded with trigger phrases, making it easy to scan. However, it could be slightly more structured (e.g., bullet points for different entity types). At 5 sentences it is concise but packs substantial information; minor improvement possible without losing clarity.

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

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

Given no output schema, the description explains return format (paired data + citation URIs) and sorting behavior. It covers data sources, entity types, edge cases (off-calendar fiscal years), and even quantifies efficiency gains. This provides a complete picture for an 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?

The input schema covers both parameters with descriptions, but the description adds significant context: for 'type' it explains what data each enum value pulls (latest 10-K metrics for company, FAERS for drug), and for 'values' it clarifies expected formats (tickers/CIKs for company, drug names). It also notes min/max items, which schema already covers, but the real-world meaning is enriched.

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 side-by-side comparisons of 2-5 companies or drugs. It lists trigger phrases like 'compare X and Y', 'X vs Y', 'which is bigger', and explicitly differentiates from sequential single-entity lookups by stating 'ALWAYS PREFER over sequential single-pack lookups'. This distinguishes it from sibling tools like 'entity_profile'.

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: for comparing multiple companies or drugs, with specific examples like 'rank these companies'. It advises preferring this tool over sequential single-entity lookups. It also details behavior for each type (company vs. drug), including handling of off-calendar fiscal years, giving the agent clear context for correct invocation.

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 (read-only, open-world, idempotent), the description discloses many behavioral traits: it never invents answers, returns gaps[] when data is unavailable, includes contradictions[] scans for standard/thorough, provides a `hop` field and fetchable citation_uri only when resolvable, semantically excerpts large records, and gives realistic latency expectations (15-60s, up to ~90s for thorough). This is rich transparency well beyond 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 long but every sentence earns its place, packing critical information efficiently: account requirements, alternative tool, scope, mechanism, output format, gaps/contradictions, use cases, exclusions, latency. It is front-loaded with the most actionable info (account required, use ask_pipeworx if unsigned in) before the deep details, using semicolons and parentheticals to keep structure tight.

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

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

With no output schema, the description must explain return values and behavior, and it does: findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field. It also covers failure modes (gaps for topics not in catalog), timing, and second-hop iteration. For a complex tool with 2 params and no output schema, this is complete and self-sufficient.

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

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

The schema already covers both parameters 100%, so baseline is 3. The description adds valuable meaning: it explains that 'question' can be broad/multi-part because decomposition is the point, and it elaborates the depth enum (quick/standard/thorough) with behavioral consequences like gap recovery and contradiction scans, plus the paid-plan requirement for 'thorough'. This exceeds schema coverage but is not entirely free of redundancy.

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 1455 structured data sources in one call, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes itself from open-web search and names the alternative for single lookups (ask_pipeworx), so it is highly specific and sharply differentiates 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 gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. It also says to prefer ask_pipeworx for breaking/current-news topics because deep_research will return gaps[]. Account requirements are stated upfront, including that non-signed-in users should use ask_pipeworx instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns top-N most relevant tools with full schemas and curated examples, ready to call directly. No contradiction.

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

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

Description is front-loaded with purpose and usage. The list of domains is somewhat lengthy but informative. Could be slightly more concise, but overall efficient.

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

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

For a discovery tool, it fully explains what it returns (tool names, descriptions, schemas) and how to use it. No output schema but description compensates. Siblings are numerous, and description sets clear expectations.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. Description adds examples and clarifies the main parameter's purpose, but doesn't provide 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?

The description clearly states it finds tools by describing the data or task, listing many domains. It distinguishes itself from sibling tools by being the initial discovery tool, which is explicit in 'Call this FIRST'.

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 'Call this FIRST when you have many tools available and want to see the option set'. Provides context on when to use (browse, search, discover) and implies it's for exploration before other tools.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds rich behavioral context: it fans out across six sources, details return structure (cik, filings, fundamentals, patents with sunset warning, news, LEI), and notes parallel execution. This goes well beyond what annotations alone convey.

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

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

The description is detailed but efficient—front-loaded with examples and key usage rules. While it contains a dense block of return fields, the information is well-organized and each sentence serves a purpose. A minor reduction in length could improve conciseness, but it remains clear and structured.

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

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

Given the tool's complexity and lack of output schema, the description fully explains return values (cik, filings with URIs, fundamentals, patents with sunset info, news, LEI) and edge cases (patents soft-fail). No additional context is needed for proper 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%. The description adds significant meaning: it clarifies that 'type' only supports 'company' for now, explains why only ticker/CIK are valid for 'value' (names not supported), and recommends using resolve_entity as a preprocessing step. This provides essential guidance missing from the schema alone.

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

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

The description starts with explicit query examples (e.g., 'Tell me about X', 'research Acme') and states 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from sibling tools by recommending preference over chaining single-source lookups.

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

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

The description explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is needed. It also specifies input requirements (ticker or CIK, not names) and directs users to use resolve_entity if they only have a name, providing clear usage boundaries and alternatives.

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

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

Annotations already indicate destructiveHint=true, so the description's 'Delete' aligns with that. It adds context about clearing sensitive data but doesn't go beyond the annotation significantly.

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

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

Two sentences with no wasted words. The action and resource are front-loaded, and usage guidelines follow immediately. Every sentence is necessary.

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

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

For a simple tool with one parameter and annotations present, the description covers purpose, usage, and relationship to siblings fully. 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% and the description of the 'key' parameter ('Memory key to delete') does not add meaning beyond the schema definition. Baseline score of 3 applies.

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

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

The description uses a specific verb+resource ('Delete a previously stored memory by key') and distinguishes itself from sibling tools 'remember' and 'recall', clearly establishing its unique purpose.

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

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

Explicitly states when to use the tool ('context is stale, the task is done, or you want to clear sensitive data') and references sibling tools for pairing, providing clear guidance on alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context on what the tool does internally (fetches page, extracts title/description/key links) and the output format, which is valuable beyond the annotations.

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

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

The description is concise: two main sentences plus a list of use cases. It is front-loaded with the core functionality and wastes no 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 good annotations and schema coverage, the description covers the key aspects: purpose, output format, and use cases. It is sufficiently complete, though the exact output format could be slightly more detailed.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description does not add significant new semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb and resource. It also lists specific use cases, distinguishing it from related sibling tools like 'scan_competitor_ai_presence' or 'ai_visibility_check'.

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

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

The description explicitly mentions three use cases (getting a client's site indexed, drafting for own project, auditing competitor) but does not explicitly state when not to use the tool or mention alternative tools. However, the context is clear enough for an agent to decide.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds what the output contains (bio, counts, etc.) but does not disclose additional behavioral traits beyond what annotations imply.

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

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

A single sentence that efficiently captures the action, resource, input example, and output summary. 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?

The description is complete for a simple tool with one parameter and an existing output schema. It mentions key return fields, making it sufficient for an agent to understand the tool's purpose.

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

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

Schema coverage is 100%; the schema already includes a clear description and example for the id parameter. The description's mention of 'by ID' adds no new semantic 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 uses a specific verb 'Get' and resource 'Mastodon account profile', clearly indicating the input (ID) and output (bio, counts, post history, verification status). It distinguishes from all sibling tools, none of which are for account retrieval.

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

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

The description implicitly states when to use (need account by ID) but does not explicitly mention when not to use or alternatives. However, given the tool's simplicity and lack of similar siblings, the guidance is still clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the return format but does not disclose potential rate limits, pagination, or other behavioral traits beyond 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?

Single sentence, no wasted words. All information is front-loaded and necessary.

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

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

For a simple read-only tool with a clear output schema (implied), the description covers the essential purpose and return content. No gaps identified.

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

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

Schema coverage is 100% for the single limit parameter. The description does not add details beyond the schema, so baseline 3 is appropriate.

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

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

The description specifies the action ('Get recent posts'), the resource ('public Mastodon timeline'), and the returned fields ('statuses with authors, timestamps, engagement counts, and content'). This clearly distinguishes it from sibling tools like get_trending.

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

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

No guidance on when to use this tool versus alternatives (e.g., get_trending). No mention of prerequisites or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about return values (engagement counts, authors, tags) but no behavioral traits beyond annotations. No contradictions.

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

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

Two concise sentences with front-loaded purpose. No redundant or irrelevant content. Every word adds value.

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

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

For a simple read-only tool with one parameter and good annotations, the description is complete enough. It specifies output content, though it omits potential pagination or rate limits. Still adequate given the tool's simplicity.

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

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

Schema description coverage is 100%, with the 'limit' parameter fully described (default, max). The description does not add additional semantics beyond what the schema provides, so 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?

The description clearly states the tool retrieves trending posts from Mastodon and lists returned data (engagement counts, authors, tags). It is specific about the resource and action, but does not explicitly distinguish from siblings like 'get_timeline' or 'pipeworx_trending'.

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

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

No guidance on when to use this tool versus alternatives. The description implies it is for trending content but does not discuss exclusions or context, leaving agents to infer usage.

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

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

Annotations already indicate readOnly, idempotent, non-destructive nature. Description adds value by listing the exact fields returned (id, type, params, etc.) and noting the optional include_inactive parameter, enhancing transparency.

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

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

Two concise sentences, each serving a distinct purpose: stating the function and providing usage guidance. No redundant or extraneous 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?

Given no output schema, the description adequately covers returned fields. Annotations cover safety. Some may want pagination info, but for a small list it's acceptable. Lacks only minor details like ordering.

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

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

Schema has 100% coverage for the single parameter. Description adds minimal extra meaning beyond what the schema already provides (just implies default of active subscriptions). 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 it lists the caller's active subscriptions with a specific verb and resource. While it doesn't explicitly distinguish from other list tools in the sibling list, the context of subscriptions makes it clear.

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

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

Provides explicit guidance on when to use the tool: before adding more subscriptions or to find an id to cancel. Does not name alternatives but implicitly differentiates from subscribe/unsubscribe.

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 are all false, leaving the description to carry the burden. It discloses rate limiting (5/day), that it's free and doesn't count against quota, the claim_token flow for checking resolution, and that the team reads digests daily. 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 a single, well-organized paragraph that front-loads the purpose, then covers usage, behavioral nuances, and constraints. Every sentence adds unique, non-redundant information. Appropriate length given 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?

Despite no output schema, the description fully explains the return behavior via claim_token and the resolution-checking flow. It also covers rate limits, quota impact, scope limitations, and guidance for crafting feedback. No gaps for the agent to operate 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 covers 100% of parameters with descriptions, so baseline is 3. The description adds valuable semantics beyond schema: instructs users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, and clarifies claim_token usage ('with no other arguments'). This extra context 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes the feedback tool from all sibling tools, which are research/management tools, by focusing on reporting issues about Pipeworx itself.

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 when-to-use guidance is provided: use for bugs, feature requests, data gaps, or praise. It also gives a clear exclusion: do not report issues from other MCP servers, and explains how to identify Pipeworx tools. 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?

Discloses caching duration, data source (CF analytics-engine), no PII, and self-aggregating signal. Adds value beyond annotations which already indicate read-only, idempotent, non-destructive.

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: main action first, then use cases, then technical details. Every sentence adds value; no redundancy.

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

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

Given the tool's simplicity (one optional param, no output schema) and full annotations, the description covers behavior, caching, use cases, and data origin completely.

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

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

Single parameter 'window' is fully described with enum values and added semantics: shorter windows surface current trends, longer windows show steady-state demand. Schema coverage is 100%, and description enriches it.

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

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

The description clearly states the tool returns top tools, top packs, and call volume over a window. It distinguishes from siblings like get_trending by specifying its focus on Pipeworx agent activity.

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

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

Explicitly lists three specific use cases and differentiates between short and long windows. Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

Annotations declare readOnlyHint and idempotentHint, which align with the read-only computation nature. The description adds rich behavioral details: monotonicity checks, partition sums, semantic anchoring, placeholder filtering, and CLOB depth fill checks. 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 thorough and well-structured, starting with the core purpose then detailing each mode and behavior. Every sentence provides useful information, though slightly verbose for some readers. Could be tightened without losing clarity.

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

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

For a complex tool with no output schema, the description fully explains return fields (opportunities array, partition_check object), covering all modes and edge cases (low similarity, placeholder fraction, fill check). Includes practical warnings and cross-reference to sibling tools, making it self-contained enough for correct 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 already documents both parameters. The description adds significant value by explaining the behavior of each mode with examples (event slug type, topic seed question), how the tool processes them (walks child markets, searches related events), and the algorithm applied. High schema coverage does not diminish the added semantic 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?

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Verb and resource are explicit, and it distinguishes from sibling tools like polymarket_edges.

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

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

Explicitly describes three modes (no args for trending_scan, event for specific market, topic for cross-event scan) and provides recommendations. Includes when-not-to-use warnings such as the Jaccard similarity threshold and placeholder filters, plus the fill check condition for not trading when realizable_edge_pp ≤ 0. References sibling tool for custom sizing.

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

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

Annotations already indicate readOnlyHint and idempotentHint, and the description adds extensive behavioral context: caching at KV level, model family details, tradeable-edge knobs, diagnostics, and Fed market caveats. 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 and dense with technical details (e.g., specific alpha values, funnel counters). While well-structured with numbered segments, it could be more concise. Every sentence adds value, but overall verbosity reduces readability for quick scanning.

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 (9 parameters, nested output, no output schema), the description is exceptionally complete. It explains the response structure (by_segment, fed section, diagnostics), model logic, and filter effects, leaving little ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how parameters interact (e.g., slippage_pp advice, min_partition_leg_kelly vs min_kelly distinction), justifying an above-baseline score.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'Polymarket markets', and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly states the tool is built for 'what should I bet on today' agents and explains how to use filter knobs. However, it does not explicitly mention when not to use it or provide alternatives beyond the implicit differentiation from siblings.

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

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

The description goes beyond annotations by detailing the response structure (tracked[], expired[], snapshot_dates[]), how decay is computed, and limitations (60-day TTL, gaps, intraday vs. daily closes). It fully discloses behavioral traits without contradicting the readOnlyHint, openWorldHint, and other 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 the purpose and uses a structured format to detail response fields, making it easy to parse. While it is somewhat verbose, every sentence contributes useful information, achieving a good balance between conciseness and completeness.

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 the lack of an output schema, the description fully explains the return fields (tracked, expired, snapshot_dates), edge cases (snapshot gaps, TTL), and limitations. It provides sufficient context for the agent to use the tool effectively, making it complete for this complexity level.

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 coverage is 100% in the schema, and the description repeats the parameter explanations with slight additions (e.g., 'snapshot family' for window). Since the schema already provides comprehensive descriptions, the description adds limited extra semantic value, meriting a baseline score of 3.

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

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

The description clearly states the tool's purpose: providing 'Edge persistence and decay telemetry' to determine how long an edge has existed and whether it is shrinking. It uses a specific verb-resource pair and distinctively contrasts fresh vs. old edges, differentiating it from sibling tools like polymarket_edges.

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

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

The description indirectly explains when to use the tool by contrasting 'a fresh wide edge and a 3-week-old wide edge' and implying its use for understanding edge longevity. However, it does not explicitly specify when not to use it or name alternative tools, leaving room for improvement.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, no destructive. The description adds significant behavioral detail: walks order ladder, returns specific fields like vwap_fill_price, slippage, shares_filled, and warns about partial fills converting arb to unhedged position. 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 necessary given the complexity. It starts with a clear summary, then breaks down modes. Some sections are dense (e.g., return field lists) but every sentence adds value. Could be slightly more structured (e.g., bullet points) but is efficient for the information density.

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 lists return fields thoroughly (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains both modes completely. It covers parameters, defaults, return values, usage context, and risk warnings. Nothing essential is missing.

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 meaning beyond schema: explains interaction between market/event (mutual exclusivity), default side in basket mode (auto from partition sum), size_usd meaning in basket (settlement notional, shares per leg), and single-market size interpretation (max spend vs target proceeds). These details are not in schema descriptions.

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

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

The description clearly states the tool computes 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and uses specific verbs and resource (edge check). It is not a tautology and clearly differentiates from sibling tools like polymarket_arbitrage.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical edge not capturable on thin books, partial baskets convert arb to directional risk). No ambiguity about 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 annotations (readOnly, openWorld, idempotent), the description details safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), response structure, and edge cases like non-equivalent bet shapes.

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

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

Well-structured with sections and examples, though slightly verbose. Every sentence adds value, but could be tightened.

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?

Even without output schema, the description thoroughly explains the response (leg prices, spread, top_spreads_pp) and edge cases. Temporal alignment and compatibility warnings are covered.

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 context: explains interactions between parameters (e.g., overrides), gives example values, and clarifies the two modes.

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 it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishes two modes (topic shortcuts vs explicit tickers), and differentiates from sibling tools like polymarket_arbitrage.

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 guides when to use topic mode vs explicit parameters, warns that most pre-mapped topics may not return tradeable spreads, and explains compatibility_warning conditions when spreads are meaningless.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about scoping to an identifier and the lifecycle pairing with remember/forget, which is valuable 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?

Three sentences, each essential: primary action, usage context, and lifecycle. No wasted words, front-loaded with the core functionality.

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

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

Given the simple schema and full annotations, the description covers key behaviors (retrieve vs. list, scope, pairing with siblings). No gaps remain for effective tool invocation.

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

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

Schema coverage is 100% with a clear description for the key parameter. The description reinforces the optionality (omit to list all keys) and adds concrete examples of memory contents (ticker, address, research notes), enhancing understanding.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys. It distinguishes from siblings by mentioning pairing with remember and forget, making the purpose specific and well-differentiated.

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

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

The description explains when to use the tool (look up stored context without re-deriving) and references alternatives (saving with remember, deleting with forget). It lacks explicit when-not statements but provides sufficient contextual 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it explains that mark_read:true flags returned events as read so subsequent calls return newer ones, and describes the return format in detail. This goes beyond the annotations without contradiction.

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

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

The description is a single paragraph with front-loaded purpose, and each sentence adds meaningful information: purpose, return fields, filtering options, mark_read behavior, and polling/alternative endpoint. 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?

Without an output schema, the description adequately covers return fields (source, citation_uri, payload), parameter usage, and behavioral nuances like mark_read. It does not mention error handling or edge cases, but for a simple read-only tool with robust annotations, it is sufficiently complete.

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

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

All 5 parameters are documented in the schema (100% coverage), so baseline is 3. The description adds context by explaining the effect of mark_read ('flag returned events read so the next call only shows newer ones') and explicitly mentions filtering by type and ISO timestamp, enhancing understanding beyond the schema descriptions.

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

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

The description clearly states the tool retrieves fired events from a subscription feed, specifies return fields (source, citation_uri, payload), and mentions filtering options. This distinguishes it from sibling tools as no other tool handles alerts.

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 notes that 'Polls work fine' and provides an alternative REST endpoint (GET registry.pipeworx.io/alerts.json), offering clear context for when to use this tool vs. direct HTTP access. However, it does not explicitly state when not to use the tool among sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing it as a safe, read-only tool. The description adds valuable behavioral context: parallel fan-out to multiple sources, fallback logic (GDELT preferred, GNews on rate limit/5xx), soft-failure for USPTO, and the return format (structured changes grouped by source, total_changes count, pipeworx:// citation URIs). No contradiction with annotations.

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

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

The description is moderately long but well-structured. It front-loads with example queries and core purpose, then systematically covers sources, parameter details, return format, and alternative tools. Each sentence adds value without redundancy. A slight reduction could make it even tighter, but it remains efficient.

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

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

Given the tool's complexity (multiple data sources, fallback logic, special date formats) and the absence of an output schema, the description is remarkably complete. It explains what sources are consulted, how fallback works, the `since` parameter formats, the output structure, and directs to the sibling tool for static profiles. The annotations cover safety and idempotency. An AI agent has sufficient information to decide when and how to invoke this 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 baseline is 3. The description goes beyond by explaining the 'since' parameter accepts both ISO dates and relative shorthand (with examples '7d', '30d', '1y'), specifying for 'value' it can be a ticker or zero-padded CIK, and clarifying 'type' is currently limited to 'company'. This adds practical usage guidance beyond the schema definitions.

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

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

The description starts with example queries ('What's new with X', 'latest on Y') and clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It identifies specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes itself from the sibling tool 'entity_profile', which serves the complementary use case of static profiles.

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

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

The description explicitly tells when to use this tool vs alternatives ('Use entity_profile instead when you want the static profile...'), and provides example natural language queries. It implies usage for recent changes but does not explicitly state when not to use it (e.g., for historical data beyond a few years).

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 idempotent and non-destructive. Description adds important details: persistence scoping, session duration for anonymous (24 hours), and key-value storage mechanism. 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?

Paragraph is concise, front-loaded with purpose, then usage, then technical details. 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 2-parameter tool with no output schema, the description covers purpose, usage, behavior, and parameter guidance. Missing only what the return value or confirmation looks like, but otherwise 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 has 100% coverage with good descriptions for 'key' and 'value'. The description adds example values but does not provide significant additional meaning beyond the schema. Baseline 3.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, with specific verb 'Save' and resource 'data'. Distinguishes from siblings 'recall' and 'forget' by mentioning pairing.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Provides context on scoping (by identifier) and persistence (authenticated vs anonymous). Clear guidance.

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

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

The description adds substantial behavioral context beyond annotations: it cascades through multiple lookup endpoints, replaces 2-3 manual lookups, labels every identifier with its source, explicitly states unresolved identifiers, and guarantees graceful degradation if GLEIF/OpenFIGI are unavailable. Annotations (read-only, idempotent) are consistent and the description enriches them with operational details.

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

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

The description is long but information-dense. It opens with query examples, states purpose, gives usage direction, and then details both supported types with output specifics and fallback behavior. No sentence is redundant, though it could be slightly trimmed. The structure is logical, and the length is justified by the tool's complexity (two entity types, multiple identifier sources).

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: identifiers for each source, labeling with provenance, explicit unresolved list, and graceful degradation. It also covers edge cases (unavailable external services) and even mentions a citation URL for drug lookups. Given the tool's scope, the description 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?

The schema covers 100% of parameters with clear descriptions, so the baseline is 3. The description adds value by contextualizing what each parameter type returns (e.g., '10-digit CIK + ticker + company_name from SEC EDGAR', 'RxCUI + ingredient + brand from RxNorm'), and provides concrete examples like 'AAPL' and 'ozempic'. This goes beyond the schema's terse explanations and supports correct input formatting.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists specific examples ('What's the ticker for…', 'find the CIK for…') and distinguishes itself from siblings by emphasizing it provides IDs needed by other tools. The supported types are explicitly broken down into 'company' and 'drug', each with details on what identifiers are returned.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also outlines what inputs are accepted for each type. However, it does not name specific alternative tools or state when not to use it, though the 'Use FIRST' phrasing implies priority. The lack of explicit alternatives keeps it from a 5.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds that it internally calls 'ai_visibility_check' per entity, ranks results, and surfaces most/least recognized. 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?

Two sentences: first states purpose and mechanism, second provides usage context. Front-loaded with key action and output. Every sentence adds value; no fluff.

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

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

Despite lacking output schema, description clearly states it returns 'ranked list with score, confidence, signal density per entity'. Covers all necessary aspects: input, process, output, use case.

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

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

Schema coverage is 100% but description adds valuable semantics: 'first entry treated as the subject for narrative; rest are competitors'. This helps interpret the 'entities' parameter beyond the schema.

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

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

Description uses specific verb 'compare' and resource 'AI visibility across multiple entities'. It clearly distinguishes from sibling 'ai_visibility_check' (single entity) by stating it probes multiple entities side-by-side and ranks them.

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

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

Provides explicit use case: 'competitive AI-marketing audits' and an example question. Does not explicitly state when not to use or mention alternatives like 'ai_visibility_check' for single entity, but context is clear enough.

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. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed will list timeouts.

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

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

The description is somewhat lengthy but well-structured and information-dense. Every sentence adds value, though it could be slightly more concise.

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

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

No output schema exists, so the description fully compensates by detailing the return structure (summary block, per-advisory detail, links, alternative versions) and error handling (partial failures).

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 package and version described). Description adds context by explaining defaults and composite behavior, but the schema already provides adequate definitions.

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

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

The description explicitly states it is a composite check for npm packages, covering license, advisories, version history, and bundle size. It clearly distinguishes from sibling tools that are unrelated (e.g., AI visibility, betting, search).

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

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

The description provides explicit use cases ('is X safe / popular / small' or 'what does adding lodash cost me'), specifies NPM-only scope in v1, and directs to alternatives (deps.dev:version) for other ecosystems.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description need not repeat those. It adds that results include follower counts and engagement metrics, which provides useful behavioral context beyond the schema. However, it doesn't disclose any additional behavioral traits like rate limits or authentication needs.

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

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

Description is a single efficient sentence with no wasted words. It front-loads the main purpose and adds output details concisely.

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 output schema exists, the description adequately covers return values by mentioning follower counts and engagement metrics. It could mention the default type (statuses) but the schema covers that. Overall complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already details all parameters. The description does not add new parameter-level semantics beyond what the schema provides. The examples in the input schema are helpful but not part of the description.

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

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

Description clearly states the tool searches Mastodon for accounts, statuses, or hashtags, specifying the resource and result types including profiles, posts, and tags with follower counts and engagement metrics. This distinguishes it from siblings like 'search_within' or 'deep_research'.

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 for searching Mastodon content but does not explicitly state when to use this tool versus siblings like 'search_within' or 'deep_research'. No when-not guidance is provided.

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

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

Adds concrete details beyond annotations: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation, returns character offsets and similarity scores. Annotations already declare readOnly, idempotent, and non-destructive; 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?

Dense paragraph front-loads key idea; every sentence adds value. Could be slightly more structured but is appropriately sized and 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?

No output schema, but description explains output format (passages with offsets and scores), embedding details, character cap, and pairing with another tool. Complete for a 3-param search tool with no nested objects.

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

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

Schema coverage is 100%, but description enriches 'text' with example types and 200K char limit, 'query' with natural-language examples, and 'limit' with default value. Adds meaningful context beyond schema.

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

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

The description clearly states it performs semantic search inside a provided text, specifying the verb 'search', resource 'text content', and scope 'inside a fetched record'. It distinguishes from sibling tools by noting it's for large records and pairs with ask_pipeworx_grounded.

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 'Use when the record is too big to cram into the prompt' and describes the return format (passages with offsets). Mentions pairing with ask_pipeworx_grounded for grounded answers. Lacks explicit when-not-to-use, but positive guidance is strong.

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

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

Beyond annotations (readOnlyHint: false, openWorldHint: true, idempotentHint: true, destructiveHint: false), the description discloses requirement for OAuth account, return of subscription id, rate limits on SMS (10/day), webhook auto-disable after 10 failures, and delivery channel constraints. It adds substantial behavioral context.

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

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

The description is concise but thorough, using clear sectioning for purpose, requirements, types, and delivery channels. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple types, no output schema), the description covers purpose, inputs, outputs, prerequisites, and behavioral traits. It provides enough detail for correct 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?

With 100% schema description coverage, the description enriches each parameter with concrete examples and constraints (e.g., SEC 8-K items, polymarket topic, phone verification). It clarifies nested object structures and provides delivery channel specifics 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 'Create a proactive monitoring subscription to a live-data event stream.' It identifies the resource (subscription) and action (create), and distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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 prerequisites (OAuth account) and gives context for each subscription type. While it doesn't explicitly state when not to use this tool, it implies that only authenticated users can persist subscriptions, effectively excluding anonymous users.

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 behavior. The description adds valuable context: returns category-bucketed example questions with tool arguments, drawn from a live catalog. 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?

Description is front-loaded with common queries, then structured with details. While lengthy, each sentence provides necessary context without redundancy. Could be slightly more concise but remains effective.

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

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

No output schema exists, so the description fully covers what is returned (category-bucketed example questions with exact tool and argument shape). Also explains the source (live catalog) and optional topic filtering. Complete for this tool.

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

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

Schema coverage is 100%, but the description adds meaning by specifying example topics (finance, pharma, etc.) and explaining that omitting topic yields a cross-category spread. This aids agent in parameter selection.

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

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

The description clearly states the tool's purpose as an onboarding entry point for new agents, providing example questions. It distinguishes itself by recommending use before exploring other tools and names sibling meta-tools like 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?

Explicitly states when to use: when the agent doesn't know Pipeworx's capabilities or to learn meta-tools. Also explains optional topic parameter for focus, and lists sibling tools as alternatives for specific queries.

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

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

Adds key behavioral context beyond annotations: row is deactivated (not deleted), history preserved via recent_alerts. This explains side effects and data lifecycle.

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 focused sentences, front-loaded with action, no redundant words. Every sentence adds value.

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

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

Covers action, ownership, and effect on data. Lacks mention of return value, but for a simple idempotent mutation this is minor. Well-rounded overall.

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 the single parameter fully (id as uuid from subscribe). Description adds little beyond 'by id', but ownership enforcement indirectly relates. Baseline 3 due to 100% 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?

Describes canceling a subscription by id, clearly distinguishing from sibling tools like subscribe and list_subscriptions. Verb 'Cancel' and resource 'subscription' are specific and unambiguous.

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

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

States ownership enforcement (only your own subscriptions). Clear context for use, though lacks explicit when-not-to-use or comparison to alternatives. Still strong 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?

Beyond the read-only/idempotent annotations, the description adds critical nuance: it defines the verdicts, explains the special meaning of could_not_verify (not evidence) and unsupported, and discloses the internal pipeline routing. This is significant behavioral context that prevents misuse.

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 densely informative, starting with trigger phrases and a clear purpose, then covering usage, output, and caveats. While long, each sentence contributes value, though it could be slightly tightened in the middle.

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

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

With no output schema, the description fully explains return values: a verdict from the enumerated list, the actual value with citation, and reasoning. It also clarifies the two edge-case verdicts (could_not_verify vs unsupported), which is essential for correct interpretation.

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?

Both parameters are already described in the schema with 100% coverage, so the description adds little beyond mentioning 'exact percent-delta math' for financial claims. The schema's tolerance_pct explanation is more detailed than the description's, so the description does not need to compensate.

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 'natural-language claim verification against authoritative sources' and provides a specific verb ('fact check'/'verify'). It distinguishes itself from sibling tools by focusing on returning a verdict with grounded evidence, making its purpose unambiguous.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes two usage paths (structured SEC EDGAR vs grounded pipeline) but does not explicitly name alternative tools or exclusions, so it lacks full comparative guidance.

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