Salesforce

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

Description aligns with annotations (readOnly, idempotent, non-destructive) and adds context: explains that probing is read-only, cost implications for Anthropic (BYO key), and the structure of returned data (per-model results + combined view).

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 pack all essential information: purpose, default behavior, optional parameter usage, and return structure. No redundancy or filler.

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

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

For a tool with no output schema, the description adequately explains the return format (per-model objects with score, confidence, signals, raw_response plus combined view). Covers all parameters and use cases. Lacks mention of rate limits or pagination, but not critical 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% with good descriptions. The description further enriches by explaining the default model, the purpose of _apiKey (BYO key for Anthropic), and how context helps disambiguate entities. This adds 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 uses a specific verb 'probe' and resource 'LLMs', clearly states the outcome 'score visibility (0-100) per model', and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on multi-model probing and scoring.

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

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

Explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides guidance on default vs. additional model usage with API key. However, lacks explicit when-not-to-use or direct comparison to similar 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 mark readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context such as routing to the appropriate tool, filling arguments, returning stable pipeworx:// citation URIs, working on every tier, and being a 'one fast call'. It does not contradict annotations, but it omits potential failure modes or limitations like rate limits.

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 longer than average but information-dense. It is front-loaded with 'PREFER OVER WEB SEARCH' and covers domains, triggers, examples, alternatives, and upgrades. The list of domains is broad but useful for setting expectations. No sentence is purely filler, though it could be slightly tightened without losing 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 complex router tool with no output schema, the description is remarkably complete. It explains the tool's behavior, covers many use cases, provides concrete examples, names alternatives, and even addresses edge cases like breaking news. It gives the agent enough context to invoke the tool correctly and know what to expect.

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

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

Schema coverage is 100% with descriptions for each alias parameter, so the baseline is 3. The description adds example questions and trigger phrases, but these are more about usage than parameter semantics. It does not add significant meaning beyond the schema's own description of the question parameter and its aliases.

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 what the tool does: it answers factual questions about current/historical data by routing to one of 5,529 tools and returning structured answers with citation URIs. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx_grounded and deep_research, and positions itself as the default entry point.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', lists trigger phrases ('what is', 'look up', 'find', etc.), and says 'START HERE for most questions'. It also gives clear alternatives with reasons, e.g., use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: candidate routing improvements are enabled live, currently no candidate is active so it matches ask_pipeworx exactly, and it 'Falls back to nothing — this IS a full working router.' This goes beyond annotations without contradicting them.

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

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

The description is information-dense but each sentence earns its place: identity, current state, usage guidance, and reassurance. It is front-loaded with the key phrase 'Beta version of ask_pipeworx' and remains efficient despite its length.

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 beta router with no output schema, the description covers identity, behavioral differences, current status, and usage. It mentions 'same response shape' to address return expectations. It could elaborate on potential instability or failure modes, but overall it is reasonably 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% with aliases fully documented in the input schema. The description only says 'same arguments' without adding further parameter-level detail. Since the schema already carries the load, the baseline 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 this is the 'Beta version of ask_pipeworx: identical universal router' with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling ask_pipeworx by being the experimental edge, making the purpose and differentiation explicit.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router, implying ask_pipeworx as the alternative. It does not explicitly mention when not to use or other alternatives like ask_pipeworx_grounded, but the usage context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description goes far beyond these by disclosing exact refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the use of ONLY tool result content, and the extra LLM call cost. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and contains dense, high-value information. It is slightly longer than minimal but every sentence adds essential context (cost, refusal formats, use cases). No filler or redundancy.

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

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

Despite lacking an output schema, the description fully specifies the success and refusal return shapes, including field names and refusal reasons. It also covers performance trade-offs and use cases, making it complete for a high-stakes query tool.

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

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

Schema description coverage is 100% – all parameters are aliases of 'question' and are fully described in the schema. The description adds no additional parameter detail, but the baseline of 3 applies because the schema does the heavy lifting and the single conceptual parameter is clear.

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 is a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb ('extracts the answer') and resource. It explicitly distinguishes itself from the sibling 'ask_pipeworx' by describing the same routing but with added extraction and evidence guarantees.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups). It also names the alternative for casual queries: 'prefer ask_pipeworx for casual lookups.'

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 covers behavioral traits beyond annotations: market resolution, classification, fan-out to data packs, response shapes, resolver contract, parent_event extractor, news fields, safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread warnings), and resolution-rule risk. It does not contradict any annotations (readOnlyHint, idempotentHint, etc.) and adds significant value.

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

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

The description is well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) but is very long. Every sentence provides information, but the length may hinder quick scanning. A more concise version could retain key points while removing some detail that could be inferred from schema or output.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It covers input handling, resolution logic, fan-out details, output structure, safety behaviors, and edge cases like closed markets and resolution rules. No gaps are evident; even practical warnings from audited ledgers are included.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: clarifies market input formats (slug, URL, question text) with examples, explains depth options and include_raw behavior. It also provides classifiers and fan-out examples that enrich understanding of how parameters affect behavior.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input forms (slug, URL, question text) and explicitly states use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides clear usage scenarios, classifiers, and fan-out examples. It tells when to use the tool but does not explicitly state when not to use it or mention alternatives. The context is helpful and specific, but exclusions would improve clarity.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds value by explaining results are sorted by primary metric, citation URIs are returned, and it replaces 8–15 sequential lookups. 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?

Front-loaded with trigger phrases. Every sentence adds value: trigger examples, tool purpose, data details, sorting behavior, efficiency claim. No redundant text.

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

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

No output schema, but description explains output includes paired data plus citation URIs. Covers input, behavior, and output expectations. Also addresses edge case of off-calendar fiscal years. Complete for a tool with 2 parameters.

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

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

Schema coverage is 100%. Description enriches parameter meaning: explains that type='company' pulls latest 10-K data, type='drug' pulls FAERS/FDA/trial data, and values format for each type. Adds behavioral context like off-calendar fiscal year handling.

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

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

Description starts with user trigger phrases, then clearly defines the tool as 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It specifies data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinicaltrials for drugs) and distinguishes from single-entity lookups 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides example user queries that should trigger this tool, giving clear context for when to use it over alternatives.

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

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

The description adds extensive context beyond the annotations: account requirements, paid plan for 'thorough', expected latency (15-60s, up to ~90s), return format (findings packet with verbatim evidence, confidence, source, fetched_at, gaps[], contradictions[]), and citation resolution guarantees. It also discloses that large records are semantically excerpted and that gaps[] are never invented. This goes well beyond the readOnly/openWorld/idempotent hints.

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, but every sentence carries substantive information about usage, output, or behavior. It lacks visual structure (bullets/headings) which could improve scannability, but the content justifies its length for a tool of this complexity. Slight deduction for being a wall of text rather than organized sections.

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

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

Given no output schema, the description fully explains the return shape (findings packet, gaps[], contradictions[], hop field, citation_uri) and covers prerequisites, time expectations, and limitations. It handles the tool's complexity (parallel routing, depth tiers, gap recovery) thoroughly, leaving no major functional aspect unexplained.

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 meaningful depth semantics beyond the enum descriptions (e.g., 'standard' re-angles unanswered gaps, 'thorough' chases leads) and clarifies that 'question' supports broad/multi-part queries. It doesn't fully reinvent the wheel but adds useful operational nuance, warranting a 4.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with a specific verb 'research' and resource. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx and noting it is 'NOT open-web search'. The detail about decomposing questions into facets and routing to 5,529 tools further specifies the unique value.

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: 'Best for broad/multi-part questions over structured data', and gives clear alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. It also includes account requirements and a fallback if not signed in, making usage criteria unambiguous.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds that results are 'ready to call directly, no second schema lookup needed', enhancing transparency 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?

Single paragraph with front-loaded purpose, but could be more structured (e.g., separate usage, return). No wasted sentences.

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 return format well. With 6 params (1 required) and read-only nature, coverage is adequate.

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

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

Schema coverage is 100%, so baseline is 3. Description adds little beyond listing aliases already in schema; examples are in schema itself.

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 finds tools by describing data or task, lists specific domains, and explains what is returned (names, descriptions, schemas). Differentiates from siblings by positioning as first call for browsing.

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

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

Explicitly says to use when browsing or discovering tools, and states 'Call this FIRST' when many tools available. Does not name alternatives 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 already indicate read-only, idempotent, non-destructive. The description adds value by detailing the specific data sources (SEC, XBRL, USPTO, news, GLEIF), the soft-fail condition for patents, and the structure of the return. Minor gap: doesn't mention network calls or rate limits, but overall strong.

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

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

The description is fairly long and includes procedural details (soft-fail note, output structure). While front-loaded with examples, it could be more concise. Still, it is well-structured and easy to parse.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers what the tool returns: CIK, company name, recent filings with URIs, fundamentals sorted by period, patents (with caveat), news, and LEI. It also explains the fallback mechanisms. No missing critical context.

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

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

Schema coverage is 100%. The description reinforces the schema by repeating the format requirements for 'value' (ticker or zero-padded CIK) and clarifying that names are not supported. It adds context that 'type' currently only supports 'company'. This provides meaningful guidance beyond the schema.

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

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

The description uses specific verbs ('profile', 'returns') and clearly states the resource: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' This meets the highest standard.

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

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

Explicitly tells when to use (holistic view) and when not to (names not supported, use resolve_entity first). It also mentions the preference over chaining, providing clear context and alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and when to use it (stale context, done tasks), which supplements the annotations. No contradictions are present.

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

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

The description is two sentences long, front-loading the purpose and immediately following with usage guidelines. Every word is necessary and no redundant information is present.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, usage, and related tools comprehensively. There are no gaps in understanding how or when to use 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?

The schema coverage is 100% with a description for the 'key' parameter. The description does not add additional semantics beyond what the schema provides, so it meets the baseline of 3.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb (delete) and resource (memory). It distinguishes from sibling tools like 'remember' and 'recall' by explicitly mentioning them, and the action is unambiguous.

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

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

The description provides explicit guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall'. While it doesn't state explicit when-not-to-use scenarios, the guidance is clear and helpful.

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 behavioral traits beyond annotations: fetches page, extracts title/description/links, emits markdown. Consistent with readOnly, idempotent, openWorld hints. 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?

One efficient paragraph, front-loaded with key action and audience, 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 2-param, no-output-schema tool, the description fully explains input, process, and output format (text blob for site-root/llms.txt). Complete and actionable.

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

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

Schema coverage is 100%, so baseline 3. Description adds no extra meaning beyond schema param descriptions; does not elaborate on URL format or max_links default behavior.

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

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

Clearly states the tool generates an llms.txt file for a URL, with specific verb and resource. However, it does not explicitly distinguish from siblings like scan_competitor_ai_presence, though its purpose is distinct.

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 concrete use cases (client indexing, own project drafting, competitor auditing) but lacks explicit 'when not to use' or comparisons to alternative 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 convey readOnly, idempotent, non-destructive hints. The description adds value by detailing returned fields and confirming default scope (active only). 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 sentences, front-loaded with purpose, no redundancy. Efficient and clear.

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

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

For a simple list tool with one optional parameter, the description fully covers purpose, output, and usage context. No output schema needed.

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

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

Schema coverage is 100% with a clear description for the single boolean parameter. Description adds no further parameter info but is consistent with schema.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies returned fields (id, type, params, etc.), distinguishing it from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly advises using this tool to review monitored subscriptions before adding more or to find an ID to cancel, providing clear context for 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 (which only say readOnlyHint=false), the description discloses key behaviors: rate-limiting to 5 per identifier per day, the claim_token mechanism for later status checks, that it is free and doesn't count against quota, and that the team reads digests daily. This significantly enriches the agent's understanding of side effects and constraints.

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 yet every sentence adds unique information—scope, alternatives, return mechanism, rate limit, and contribution to roadmap. It is front-loaded with the core purpose and uses clear structuring, making it easy to parse despite its length.

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 lack of an output schema, the description adequately covers return behavior (claim_token and reading later), prerequisites (no account required), constraints (rate limit), and scope boundaries. It is complete for a feedback tool with optional parameters and no required fields.

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

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

While the schema already covers 100% of parameters, the description adds meaningful usage context: it instructs users not to paste the end-user's prompt, explains how to use claim_token (pass it back with no other arguments to read the reply), and frames the context parameter as optional structured context. This goes beyond the schema's baseline 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 begins with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools by stating it is only for Pipeworx-served tools and not for tools from other MCP servers, 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 when to use: for bugs, feature/data_gap requests, and praise. Provides a clear exclusion: do not use for tools from other MCP servers, and directs users to file with that server instead. Also clarifies what counts as a Pipeworx tool, giving concrete when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: caching (5min-1h), self-aggregating, no PII, source from CF analytics-engine. No contradiction with annotations.

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

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

Three sentences, front-loaded with core purpose, then use cases, then technical details. 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?

For a simple tool with 1 optional parameter and no output schema, the description explains return values conceptually, caching, and source. Lacks explicit format but sufficient given annotations cover safety.

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% with one parameter described. Description adds guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand' and notes the default '24h', enriching the schema's enum description.

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

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

The description clearly states the verb 'Returns' and specifies the resources: 'top tools, top packs, and total call volume' over a window. It distinguishes this tool from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on trending/aggregate data.

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

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

Three specific use cases are listed (discovering hot data sources, confirming canonical tool, aligning use case). Window parameter guidance explains when shorter/longer windows are appropriate. No explicit when-not-to-use, but the 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: how arbitrage detection works (monotonicity violations, partition checks), semantic anchor for cross-event pairs (Jaccard threshold), partition filter (placeholder slugs), and fill check logic (theoretical vs realizable edge). This goes well beyond annotations.

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

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

The description is thorough and well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is somewhat verbose but every sentence adds value given the tool's complexity. Front-loaded with the core purpose.

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

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

Despite no output schema or nested objects, the description fully explains return fields (opportunities, partition_check, fill check details), error conditions (low similarity, placeholder fraction >20%), and references sibling tool (polymarket_fill_risk) for custom sizing. Highly complete for a complex tool.

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

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

Schema coverage is 100% with both parameters described. The description adds significant meaning: explains event mode walks child markets and checks multiple conditions, topic mode searches related events and runs comparator, and provides examples of valid inputs (e.g., 'fed-decision-may-2026'). The no-argument behavior (trending scan) is also clarified.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three distinct modes (no args, event, topic) and differentiates from siblings like polymarket_fill_risk, making the purpose highly specific and distinguishable.

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 on when to use each mode (no args for trending scan, event for specific market, topic for cross-event scan) and recommends event for specific markets. It also explains when not to trade (if realizable edge ≤ 0). However, it does not directly compare to sibling tools, just within its own modes.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: caching at 1h, model family details, response structure with diagnostics, and the exclusion of fed_candidates from ranking. It also explains edge calculation (net of slippage) and includes warnings about market moves. This goes well 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 comprehensive but verbose. It front-loads the main purpose but then dives into extensive detail about three model families, response segments, and diagnostics. While well-structured, some redundancy exists (e.g., repeating min_kelly and min_partition_leg_kelly explanation). A slightly more concise version would improve readability.

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 9 parameters, no output schema, and complex behavior, the description is remarkably complete. It explains the three response segments (model_driven, structural_arbitrage, concentrated_longshot), the diagnostics for empty segments, caching behavior, and the fed_candidates exclusion. This equips an AI agent with everything needed to invoke the tool correctly.

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

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

The schema covers 100% of parameters, but the description adds significant meaning: it explains default values (e.g., min_edge_pp=0.5, slippage_pp=0.3), gives usage examples (e.g., min_liquidity=5000 to drop thin books), and clarifies how knobs like min_partition_leg_kelly interact with partition_overround opportunities. This exceeds the 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?

The description clearly states the tool's purpose: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('Scan') and resource ('Polymarket markets'), and the detailed explanation of model families distinguishes it from siblings 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 provides clear context: it's built for 'what should I bet on today' and helps agents discover opportunities without paging. It outlines tradeable-edge knobs and filters (min_liquidity, max_spread_pp) that control realizability. However, it does not explicitly state when to use alternatives like polymarket_arbitrage, so a 4 is warranted.

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

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

Annotations indicate read-only, open-world, idempotent. Description adds details: snapshots written on cache-miss, gaps mean no scan, decay from daily closes (net slippage), 60-day TTL limit. 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?

Long but information-dense. Front-loaded with purpose, then structured into args, response, limits. Every sentence adds value, but could be slightly more compact.

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 response is fully described: tracked objects with time-series, first_seen, trend, decay; expired objects with lifespan; snapshot dates. Limits and caveats also 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 description adds further context: lookback max 30, window families enumerated, defaults explained. Adds meaning beyond schema.

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

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

Description clearly states it provides edge persistence and decay telemetry, distinguishing from sibling 'polymarket_edges' which likely provides raw snapshots. Verb 'answers' and resource 'edge persistence' are specific.

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 arguments (days, window) and defaults. Does not explicitly state when not to use or alternatives, but context is clear given sibling tool names.

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

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

The description adds significant behavioral context beyond annotations (readOnlyHint, idempotentHint, etc.). It explains how the tool walks the order book ladder, what return fields to expect (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns that partial basket fills can cause unhedged directional risk. No contradiction with annotations.

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

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

The description is well-structured with clear sections for modes and requirements. It is slightly long but every sentence adds value given the complexity of the tool. Front-loading the core purpose and requirements helps quick understanding.

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

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

Given the tool's complexity (two modes, many return fields) and no output schema, the description covers the essential return values (top_of_book, vwap_fill_price, theoretical_sum, capture_ratio, etc.) and risk factors (thin_legs, forced_directional_risk). It is complete enough for an AI agent to invoke correctly.

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

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

Although schema coverage is 100%, the description adds deep semantics: it clarifies how 'side' defaults differ by mode, that 'size_usd' is interpreted as settlement notional in basket mode, and that 'market' and 'event' are mutually exclusive. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly telling the agent to use this tool before acting on their signals.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains the risks (partial fills converting arb into unhedged directional positions). This gives clear when-to-use and why.

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 extensive behavioral context: response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and conditions for meaningless spreads (temporal misalignment or bet-shape mismatch). This goes far 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 fairly long but well-structured: purpose, modes, response, safety fields. Every sentence adds value. Minor verbosity in the safety field explanation, but justified 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?

All parameters are covered, response structure is described, edge cases (compatibility warnings, temporal misalignment) are addressed. No output schema but the description compensates. Missing explicit mention of output format (JSON) and error handling, but overall adequate.

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

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

Schema coverage is 100% with descriptions. The tool description enriches this by explaining the two modes (topic vs. explicit tickers), how parameters interact (explicit overrides topic), and provides examples. Some redundancy with schema but adds meaningful context.

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 cross-venue spread between Polymarket and Kalshi. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on inter-venue comparison.

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

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

The description explains when to use the tool (to compare same outcome across venues) and warns that real spreads are rare and pre-mapped topics may not be tradeable. It provides context for compatibility warnings but does not explicitly contrast with sibling tools for within-venue analysis.

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 and destructiveHint=false. Description adds value by detailing listing behavior when key omitted and scoping by identifier, without contradicting annotations.

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

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

Description is concise, front-loaded with core purpose, and structured into purpose, examples, and pairing. 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 low complexity (one optional parameter, no output schema, clear annotations), the description covers functionality, scoping, and tool relationships 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?

Schema coverage is 100% and the parameter description already states 'omit to list all keys'. The tool description repeats this without adding new semantic meaning beyond what's in the schema.

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

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

The description clearly states it retrieves a value saved via 'remember' or lists all keys without the key argument. It explicitly distinguishes from sibling tools 'remember' and 'forget', making 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?

Description explains when to use (look up stored context) and provides concrete examples (ticker, address, notes). It notes scoping and pairing with remember/forget, but lacks explicit when-not-to-use guidelines.

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 context beyond annotations by explaining returned fields, mark_read side effect, and polling behavior. No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

Four concise sentences with front-loaded purpose. Every sentence adds value; no redundant or filler 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?

For a read-only, idempotent tool with no output schema, the description covers return fields, filtering, mark_read, and alternative access. Sufficient for agent invocation.

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

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

Schema coverage is 100% with descriptions. Description reinforces filtering and mark_read use but does not significantly add new meaning. Baseline 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?

Clearly states 'Pull fired events from your subscription feed' and lists returned fields. Differentiates from sibling tools by focusing on recent alerts, but no explicit sibling differentiation.

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

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

Provides guidance on filtering by type and since, how mark_read works, and notes polling suitability. Mentions an alternative REST endpoint. Does not explicitly exclude when not to use.

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

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

Discloses fan-out to multiple sources, soft-failure for USPTO due to API sunset, rate-limiting fallback, and output structure (changes[] with source grouping, total_changes, citation URIs) – all beyond the safety annotations (readOnly, openWorld, idempotent).

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 every sentence adds value, front-loading use cases with quoted examples and logically progressing to parameter details and sibling differentiation; could be slightly more compact but remains well-structured.

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

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

Given 3 required parameters, no output schema, and moderate complexity (multi-source fan-out with fallbacks), the description provides all necessary behavioral and output details for correct agent invocation.

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

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

Schema covers all 3 parameters with descriptions; the description adds concrete examples (ISO date vs relative shorthand like '30d', ticker vs CIK) and clarifies the 'type' enum, enhancing usability beyond 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 clearly states the tool aggregates changes (filings, news, patents) for a company within a time window, using specific examples like 'what's new with X' and distinguishes from sibling 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?

Provides explicit usage examples ('What's new with X', 'latest on Y'), explains fallback behavior (GDELT→GNews), and directly advises to use entity_profile for static profiles, leaving no ambiguity about when to use this 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?

Adds key behavioral details beyond annotations: key-value scoping by identifier, retention periods (persistent vs 24h), no contradictions with annotations.

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

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

Four well-structured sentences, front-loaded with purpose, 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?

Adequate for a simple store operation; covers purpose, usage pairing, and retention; no output schema needed.

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

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

Schema descriptions cover both parameters; description adds usage examples but doesn't significantly extend 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?

Description clearly states it saves data for reuse across conversations or sessions, and distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicitly tells when to use (discover something worth carrying forward) and pairs with recall/forget, but doesn't specify when not to use.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds valuable context: identifiers are source-labelled, unresolved ones appear under `unresolved` rather than being silently omitted, LEI/FIGI enrichment degrades gracefully, and it internally cascades through multiple endpoints. 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 (~170 words) but well-structured, starting with user-phrase examples, then a clear breakdown of supported types, and ending with degradation behavior. Every sentence adds information; however, it could be slightly tighter without losing meaning.

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

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

No output schema exists, but the description compensates by detailing return values: source-labelled identifiers, failed resolutions under `unresolved`, graceful degradation, and internal cascading. It fully covers both supported types and edge cases, giving the agent enough to anticipate the tool's behavior.

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

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

Schema already covers both params at 100%, but the description provides deep extra meaning: it explains what each `type` resolves to (company identity spine with CIK/ticker/LEI/FIGI; drug with RxCUI/ingredient/brand) and gives concrete examples for `value` ('AAPL', '0000320193', 'ozempic'). This goes well beyond the schema's basic descriptions.

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

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

The description clearly states it resolves a user-spoken name to canonical identifiers needed by other tools, with specific examples ('ticker', 'CIK', 'LEI'). It distinguishes itself from siblings by explicitly instructing to 'Use FIRST whenever you have a name but need an ID' and listing supported types.

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

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

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID' and gives concrete example queries. It also explains input formats for each type (ticker, CIK, company name, drug brand/generic) and notes graceful degradation when upstream sources are unavailable, helping the agent decide when to call this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds key behavioral details: probes each entity, ranks results, returns score/confidence/signal density, and notes API key requirement for Anthropic model. No contradictions.

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

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

Three sentences, front-loaded with purpose, use case, and output details. Every sentence adds value; no fluff.

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

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

Given 4 parameters, annotations, and no output schema, the description fully explains the tool's behavior, return format, and optional parameters (models, apiKey, context). It also references sibling tool ai_visibility_check for context. Complete for agent decision-making.

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

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

Schema covers 100% of parameters. Description adds semantic value by noting 'first entry treated as the subject for narrative', which aids agent in using the entities array correctly. This exceeds 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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Provides explicit use case ('competitive AI-marketing audits') and an example question. Implies not for single-entity checks (use ai_visibility_check) but does not explicitly state when to avoid or list alternatives beyond sibling naming.

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 key behaviors: fans out across two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and the sources_failed list. Annotations already indicate safe read operability; description adds essential timing and fault-tolerance 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?

Front-loaded with the key benefit ('composite check in ONE call'), followed by concise details and limitations. Every sentence adds necessary context 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?

Despite no output schema, the description thoroughly specifies return fields (summary block, advisory detail, links, versions) and handles edge cases (partial failures, timing). This fully equips the agent to interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples (scoped packages like @types/node, version format like 18.3.1) and clarifies defaulting behavior, making parameter usage more intuitive for the agent.

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

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

The description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. It distinguishes itself from siblings by specifying the NPM ecosystem and the specific services used.

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 an agent asks about safety, popularity, size, or cost of adding a package. Also notes NPM-only in v1 and mentions alternatives for other ecosystems, guiding 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?

Adds rich technical detail beyond annotations: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, character offsets for verification. 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?

Three sentences, each earning its place: purpose, usage context, technical constraints. Front-loaded with key action and resource. No wasted words.

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

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

Given no output schema, description adequately covers return values (passages, offsets, scores) and constraints. Could further clarify that only passages are returned, but overall sufficient with rich 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%, but description adds meaningful examples for 'text' and 'query', and specifies valid range and default for 'limit'. This enhances understanding beyond 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 clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and distinguishes from siblings like ask_pipeworx_grounded. The verb 'search' and resource 'inside a fetched record' are explicit.

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

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

Explicitly states when to use (record too big to cram into prompt) and compares with alternative (ask_pipeworx_grounded). Provides concrete examples and pairing strategy, giving clear decision criteria.

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

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

Annotations already indicate write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds that it returns the new record ID, which is not in annotations. However, idempotentHint=true conflicts with the description's implication of creating a new record each call, but description does not explicitly claim idempotency.

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

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

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

For a simple creation tool with complete schema, examples, and output schema, description adequately covers purpose, inputs, and output. No missing critical information.

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

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

Schema coverage is 100%, so baseline is 3. Description merely reiterates that object type and field values are needed, adding little beyond schema examples and 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?

Description clearly states 'Create a new Salesforce record', specifying verb and resource. It differentiates from sibling tools like sf_delete_record or sf_update_record by focusing on creation and mentioning return of new record ID.

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

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

Description implies usage for creation but does not explicitly guide when to use this tool over alternatives (e.g., when not to use sf_update_record). No direct comparison to 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 destructiveHint=true, so the description's mention of 'Delete' is consistent. It adds 'Returns success status,' which is useful but minimal. 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?

Single sentence, 12 words, no unnecessary information. Efficiently communicates the core action.

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

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

For a simple delete operation with full annotations and output schema, the description is complete. It covers action, parameters, and return type sufficiently.

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

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

Schema coverage is 100%, so the description's mention of 'ID' and 'object type' aligns with schema but adds no additional meaning beyond the parameter names.

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 deletes a Salesforce record by ID, specifying the action and resource. It is specific but does not differentiate from sibling tools like sf_update_record, which also uses IDs.

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

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

No guidance on when to use this tool versus alternatives (e.g., sf_update_record for soft delete, sf_query for retrieval). The description is too brief to convey context for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds value by specifying the exact types of information returned (field names, types, relationships, metadata), which is beyond the 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: first explains purpose and output, second gives usage advice. No wasted words, front-loaded with core action.

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

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

For a simple single-parameter tool with high schema coverage and an output schema, the description fully covers what the tool does, its output, and when to use it. No missing critical information.

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% (single parameter fully described). The description provides example values (Account, Opportunity) but adds minimal semantic depth beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves schema details for a Salesforce object, specifying the verb (Get), resource (schema details), and returned data (field names, types, relationships, metadata). It distinguishes from sibling tools like sf_query or sf_get_record by focusing on schema discovery.

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 advises using this tool before querying to understand available fields, providing clear context. While it doesn't explicitly exclude alternatives, the guidance is sufficient for an agent to decide when to invoke 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, idempotentHint, and openWorldHint. The description adds that it returns all fields, which is consistent and provides output clarity. 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 sentences front-load the purpose, no wasted words. Extremely concise.

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

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

Given rich annotations, output schema, and examples, the description is largely complete. It lacks explicit mention of optional fields parameter behavior but is adequate for a simple read operation.

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

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

Schema coverage is 100% with descriptions for each parameter. The description mentions object and ID but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool fetches a single Salesforce record by ID and object type, with examples. It distinguishes from siblings like sf_query or sf_search by focusing on single record retrieval.

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

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

The description implies usage for single record retrieval by ID but gives no explicit guidance on when to use versus alternatives (e.g., sf_query, sf_search) or when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe, read-only operation. The description adds that it returns object names and labels, which is helpful but not critical. Since annotations cover the behavioral traits, a score of 3 is appropriate.

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

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

The description is two concise sentences, entirely front-loaded with the key action and result. Every sentence adds value: the first states the action, the second states the return and use case. No wasted words.

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

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

For a simple listing tool with no parameters, strong annotations, and an output schema (indicated but not shown), the description is complete. It covers what the tool does, what it returns, and when to use it, which is sufficient for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, and the schema description coverage is 100%. Per guidelines, baseline is 4 when no parameters exist. The description does not need to add parameter details.

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

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

The description uses the specific verb 'List' with the resource 'SObject types' and scopes it to 'your Salesforce org'. It clearly distinguishes from sibling tools like sf_query or sf_describe by focusing on discovering all objects types rather than querying records or describing a single object.

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

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

The description explicitly states when to use: 'Use to discover queryable objects.' While it doesn't list when not to use or name alternatives, the context of sibling tools (e.g., sf_describe for single object details) makes it clear that this tool is for listing all object types, not for other operations.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it returns matching records with all requested fields, confirming the behavior and adding value beyond annotations by specifying the output scope.

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 front-load the purpose and return value, followed by a usage tip. Every sentence is necessary and no filler, making it highly concise and well-structured.

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

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

Given the single parameter and existing output schema, the description fully covers what the tool does, how to use it, and a recommended prerequisite. No gaps in context.

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

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

The schema has 100% coverage for the single parameter 'query', with a description and example. The main description also mentions SOQL and using sf_describe first, adding context beyond the schema. This compensates well.

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

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

The description clearly states the tool queries Salesforce records using SOQL and returns matching records with all requested fields. It distinguishes from sibling tools like sf_describe or sf_get_record by specifying SOQL, making 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 advises using sf_describe first to learn available fields, providing explicit guidance on when to use a prerequisite tool. While it doesn't state when not to use this tool, the advice is helpful for context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to reiterate safety. It adds value by stating that the tool returns matching records, which aligns with the annotations and provides expected output behavior.

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

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

The description is three sentences, all front-loaded with the core purpose and usage. 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?

The description is largely complete given the tool's simplicity (1 param, good annotations, output schema). It explains the broad search scope and return types. Missing explicit mention of SOSL format, but the schema examples compensate.

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 does not add meaning beyond the schema. The schema examples show SOSL syntax, but the description only mentions 'keyword,' which is slightly imprecise. Baseline score of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool searches across Salesforce objects by keyword and returns records from multiple object types like Accounts, Contacts, and Leads. It effectively distinguishes from sibling tools like sf_query (for SOQL) and sf_get_record (for single records) by emphasizing broad keyword searches.

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 advises 'Use for broad keyword searches,' providing clear context. While it doesn't explicitly state when not to use or list alternatives, the sibling tools (e.g., sf_query, sf_get_record) imply that narrow or specific queries are better handled by them.

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 behavior. Description adds that it 'Returns success status', which aligns but does not provide additional context like partial update details or error handling. 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?

Two concise sentences, no redundant information. Efficiently conveys purpose and return 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?

Simple update tool with good annotations and output schema (exists). Description covers core behavior; minor gap in not detailing success structure, but acceptable given schema.

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

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

Schema coverage is 100% with parameter descriptions. Description echoes 'Specify object type and field values', adding little beyond schema. Baseline score appropriate given high coverage.

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

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

Description clearly states action ('Update'), resource ('Salesforce record'), and method ('by ID, specify object type and field values'). Distinguishes from siblings like sf_create_record and sf_delete_record by specifying update semantics.

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?

Implies usage for updating existing records, but no explicit guidance on when to use this vs. alternatives (e.g., sf_create_record for new records). Lacks when-not-to-use or prerequisite conditions.

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

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

The description discloses authentication requirements, delivery channel constraints (SMS cap, webhook auto-disable), and return value (subscription id). However, there is a contradiction with annotations: idempotentHint=true implies idempotent behavior, but the description says each call returns a new subscription id, suggesting non-idempotent creation. This reduces 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?

The description is well-structured: first sentence states purpose and return, followed by auth requirement, type-specific details, and delivery options. While informative, it is somewhat lengthy but every sentence earns its place. A minor trim for brevity would not hurt.

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, delivery channels, no output schema), the description covers all necessary aspects: auth, type-specific parameters, delivery constraints, webhook security, and prerequisites. It leaves no major gaps for an AI agent.

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

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

With 100% schema description coverage, the description still adds significant value by providing concrete examples for each subscription type, explaining required and optional fields, and detailing delivery channel semantics (e.g., email validation, SMS verification, webhook HMAC signing). This goes well beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. The verb-resource pair is 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?

The description provides detailed guidance on when to use different subscription types (e.g., sec_8k for filings, polymarket_edge for arbitrage) and outlines prerequisites (Pipeworx OAuth account, phone verification for SMS). It does not explicitly compare to alternative tools like recent_alerts or list_subscriptions, but the 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?

Adds rich behavioral context beyond annotations: explains that it returns category-bucketed example questions with tool+argument shapes, can be called with no arguments or a topic, and draws from a live catalog. No contradiction with annotations.

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

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

The description is front-loaded with purpose and packs useful information, but is slightly verbose with multiple phrasings. Every sentence adds value, so 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 single optional parameter, full schema coverage, and rich annotations, the description fully covers the tool's behavior, output, and usage context, leaving no gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing specific topic values and explaining the effect of omitting or passing a topic, which exceeds the schema's description.

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

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

The description clearly defines the tool as an onboarding entry point that generates example questions about Pipeworx's capabilities, listing common user phrasings and distinguishing it from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear context for when to use. Does not explicitly list exclusions or alternatives, but the 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?

Description adds behavioral details beyond annotations: ownership enforcement, deactivation not deletion, historical availability. Annotations already indicate mutation and non-destructive, and description aligns and expands.

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 front-load the action and constraints. No wasted words; every sentence adds value. Highly efficient.

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

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

For a simple one-parameter tool with good annotations and no output schema, the description covers purpose, usage, and behavior completely. 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?

Single parameter 'id' is fully described in schema as 'Subscription id (uuid) returned by subscribe.' Description does not add new meaning beyond the schema, and schema coverage is 100%, so baseline 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?

Description clearly states 'Cancel a subscription by id.' with specific verb (cancel) and resource (subscription). Distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

Explicitly mentions ownership enforcement ('only cancel your own subscriptions') and explains the effect (deactivation, not deletion, with historical events retained). Provides context for when to use, though no explicit alternative is given for other actions.

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, but the description adds critical behavioral context beyond that: it explains that 'could_not_verify means the check did not happen' and carries verification_error{stage,detail}, explicitly warning it must not be shown as evidence. It also clarifies the difference between 'could_not_verify' (check not performed) and 'unsupported' (no source found), which is not inferable from annotations alone.

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

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

The description is relatively long but every sentence earns its place: example queries, routing rules, verdict meanings, caller warnings, and efficiency claim are all operationally relevant. It is front-loaded with the purpose (started with natural-language triggers) and ends with a practical note about error handling. Structure is logical, moving from general to specific.

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 thoroughly covers return values (verdicts, actual value with citation, reasoning), error semantics (could_not_verify vs unsupported), routing behavior, and usage scope. It also mentions the exact percent-delta math for financial claims, leaving little ambiguity about behavior or edge cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already fully documents the 'claim' string and 'tolerance_pct' number with examples and default behavior. The description does not add additional parameter-level details beyond mentioning tolerance in the context of percent-delta math, which is already covered in the schema. No deduction or upgrade is warranted.

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 concrete natural-language examples ('fact check', 'verify the claim that…') and clearly defines the tool as claim verification against authoritative sources. It distinguishes itself from siblings by specifying two routing paths: structured SEC EDGAR for company-financial claims and a grounded pipeline for all other factual claims. The verb 'verify' and resource 'claims' are explicit and non-tautological.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It distinguishes between company-financial claims and any other factual claim, indicating the fallback behavior. It also notes that the tool 'Replaces 4–6 sequential calls,' implying when it is more efficient than alternative multi-step approaches.

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