Notion_connect

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: cost implications (free default, BYO key for Anthropic), return structure (per-model + combined view), and default model details. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the primary action and result. Every sentence adds value: first sentence states core functionality, second explains key parameters, third lists use cases. 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?

Despite lacking an output schema, the description explains the return format clearly. All 4 parameters are covered with schema descriptions and additional context in the description. Use cases and parameter dependencies (e.g., _apiKey needed for anthropic model) are well explained. The tool is fully understandable for correct invocation.

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

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

Schema coverage is 100% with good descriptions. The description adds extra meaning by specifying the default model (Workers AI Llama-3.3-70b) and the purpose of context for disambiguation, going 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 action ('Probe one or more LLMs'), the target ('business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes this tool from siblings by focusing on AI visibility audits, which is specific and not a tautology.

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 (AI-marketing audits, pre-launch checks, competitive monitoring) and explains the optional _apiKey for Anthropic. However, it does not contrast with similar sibling tools like scan_competitor_ai_presence or compare_entities, missing an opportunity to clarify when not 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?

Description adds detail beyond annotations: it routes to many tools, returns structured answers with citation URIs. No contradictions with readOnlyHint, etc. Annotations already cover safety, so description adds 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?

Description is front-loaded with key directive and example-driven. Slightly long but every sentence adds value. 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 no output schema and 6 aliased parameters, the description explains the tool's broad capability and provides ample usage guidance. Missing details on error handling, but sufficient for effective use.

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

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

Schema coverage is 100% and description reinforces that the parameter is a natural language question. Provides aliases and examples, but doesn't add much beyond schema.

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

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

The description clearly states the tool queries authoritative structured data via routing to 3,745 tools, distinguishing it from web search. It provides specific use cases (SEC filings, FDA, etc.) and example questions.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for factual questions and lists trigger phrases ('what is', 'look up'). Provides concrete examples. Lacks explicit when-not-to-use but 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds significant behavioral context: hallucination-resistance, evidence extraction, explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the cost implication. No contradictions.

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

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

The description is a single, well-structured paragraph. It front-loads the purpose and key differentiator, then details behavior, use cases, return structure, and cost trade-off. Every sentence adds essential information without redundancy.

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

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

Despite the tool's complexity (3,745 tools, 884 sources), the description fully covers purpose, behavior, output format, refusal reasons, and when to use. No output schema exists, but the description details return fields adequately. The guidance is complete for safe and correct usage.

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

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

Schema has 6 parameters (question and 5 aliases) with 100% description coverage in schema. The tool description does not add details beyond mentioning 'question' in natural language. Schema already adequately explains each parameter, so description adds no extra value. 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 begins with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the tool's unique value. It specifies that it returns answers with evidence and refuses when data doesn't directly answer. It distinguishes itself from sibling 'ask_pipeworx' by noting extra extraction and cost.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Provides a clear alternative: 'prefer ask_pipeworx for casual lookups.' Also mentions the cost trade-off: 'Costs one extra LLM call vs ask_pipeworx.'

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 exhaustively details behavior: market resolution, classification, parallel fan-out, response shapes, safety short-circuits for low-confidence or closed markets, cancellation rules, and news error handling. Annotations indicate readOnlyHint and idempotentHint, which align with the description, and 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 very long but well-structured with section headers and capitalizations for key concepts. However, it could be more concise; the level of detail, while useful, makes it a wall of text that may be harder for an agent to parse quickly.

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

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

Given the complexity and absence of an output schema, the description fully explains return values (result.market, result.analysis, result.evidence, result.market_match_confidence, parent_event, news fields) and covers many edge cases (illiquid spreads, cancellation rules, news backfill failures). No gaps remain for an agent to understand 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%, so baseline is 3. The description adds value by providing examples for the market parameter (slug, URL, question) and explaining the depth and include_raw parameters with usage guidance and consequences (e.g., response size). This goes beyond the schema descriptions.

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

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

The description explicitly states the tool researches a Polymarket bet by pulling Pipeworx data. It provides specific use cases ('should I bet on X') and distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on single-bet research.

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

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

The description gives clear when-to-use guidance ('Use for should I bet on X, what does the data say, is there edge) and covers when to exercise caution (low-confidence, closed markets, wide spreads). It also advises inspecting market_match_confidence before trusting 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 convey read-only, idempotent, non-destructive behavior. The description adds value by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), off-calendar fiscal year handling, sorting by primary metric, and output format (paired data + citations). These details go beyond annotations, though rate limits or data freshness are not mentioned.

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

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

The description is well-structured, starting with example queries and then providing detailed data sources and behavior. It is slightly verbose but every sentence adds value. The front-loading of examples helps agents quickly understand usage. Minor reduction could improve conciseness.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description covers essential aspects: entity types, value format, data sources, sorting, and return format. It lacks explicit information on error handling or edge cases (e.g., invalid tickers), but the schema enforces constraints. The description adequately complements the rich annotations and 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?

Despite 100% schema coverage, the description adds significant meaning beyond the schema. It explains that 'type=company' pulls latest 10-K financials (revenue, net income, cash, debt) and 'type=drug' pulls FAERS counts, FDA approvals, and trial counts. It also clarifies the values parameter (tickers/CIKs for company, names for drug), which is not detailed in the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It uses specific verbs ('compare', 'compare entities') and distinguishes from siblings by explicitly preferring over sequential lookups and noting it replaces 8-15 lookups.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists example queries. It also clarifies the number of entities (2-5) and types supported, effectively telling the agent when to use this tool vs alternatives.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds key behaviors: grounded answers with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, explicit gaps[] to avoid hallucination, pre-verified facts, parallel execution, and expected response time (15-60s). Complements annotations fully.

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 front-loaded purpose and clear details. Slightly long but every sentence adds value. Could trim redundant phrasing but overall efficient.

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

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

Given the tool's complexity and lack of output schema, the description is complete. It explains what the tool returns (structured findings packet with specific fields) and the process. Minor gap: exact output schema not specified, but the natural language description suffices 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?

Schema already covers both parameters with descriptions (100% coverage). The description adds context: question should be broad/multi-part, depth mapping (quick=3, standard=5, thorough=8), and paid plan requirement for thorough. Provides useful extra meaning beyond the schema.

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

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

The description clearly identifies the tool's purpose: grounded multi-source research in one call, with parallel decomposition. It uses specific verbs and resources, and distinguishes from siblings like ask_pipeworx by highlighting multi-facet decomposition and parallel execution.

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

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

Explicit when-to-use vs alternatives: 'Use for broad or multi-part questions... use ask_pipeworx for single lookups.' Also states prerequisites (Pipeworx account) and depth limitations (thorough requires paid plan). No ambiguity.

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 show readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results are 'ready to call directly' and explains return format. No contradictions, and adds useful behavioral context beyond annotations.

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

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

Single well-structured paragraph: starts with purpose, lists examples, explains return value, and gives usage guidance. Every sentence adds value with no fluff.

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

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

Despite no output schema, description fully explains what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Also addresses query flexibility and ready-to-call nature. Complete for tool discovery use case.

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

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

Schema coverage is 100% with clear parameter descriptions. Description reiterates query aliases and limit default/max, adding marginal value. Baseline 3 is appropriate as schema already does the heavy lifting.

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

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

Description clearly states purpose: 'Find tools by describing the data or task.' Lists many specific domains (SEC filings, FDA, weather, etc.) and explains it returns top-N tools with schemas, ready to call. Distinguishes from sibling data-specific 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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Good context for when to use, though could more explicitly state when not needed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. Description adds useful behavioral context: parallel call, specific return fields, soft-fail for patents, and name unsupported. 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 examples and each sentence contributes. Slightly wordy but appropriate for complexity of the tool.

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

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

No output schema, but description lists return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and mentions limitations. Very complete for a complex multi-source tool.

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

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

Schema coverage is 100%, but description adds value by explaining parameters: type only 'company', value ticker or CIK (not names), and references resolve_entity for names. Meaningfully supplements 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 a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and outputs. It distinguishes from sibling tools like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and advises using resolve_entity first if only have a name. Also mentions limitations (names not supported, patents soft-fail).

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 use cases (stale context, clearing sensitive data) but does not reveal additional behaviors beyond what annotations state, so it slightly falls short of maximum.

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

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

The description is two sentences, front-loaded with purpose and immediately followed by usage guidance. Every sentence adds value with no extraneous 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?

Given the tool's simplicity (one parameter, no output schema, clear annotations), the description covers purpose, usage, and pairing with siblings, providing complete context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with the schema already describing 'key' as 'Memory key to delete.' The tool description does not add any additional semantic information about the parameter beyond what is 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 'Delete a previously stored memory by key,' using specific verb 'Delete' and resource 'memory by key.' It distinguishes from sibling tools 'remember' and 'recall' by being the deletion counterpart.

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 provides 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,' offering clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This provides context beyond what annotations offer, explaining the tool's process and output.

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 with three sentences that front-load the core purpose and output format. Every sentence adds value, but it could be slightly more structured (e.g., separate use cases). Still, it is efficient with no wasted words.

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

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

Given the tool has no output schema, the description compensates by explaining the output ('single text blob ready to drop at site-root/llms.txt'). It covers use cases and basic behavior. For a simple tool with only two parameters and rich annotations, this is adequately complete, though it omits error handling or limitations.

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

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

Input schema has 100% description coverage for both parameters (url and max_links). The description does not add new meaning beyond the schema; it mentions max_links defaults but those are already in the schema's description. Baseline 3 is appropriate as the schema carries the burden.

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 generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It also lists specific use cases (client indexing, own project, competitor audit) that distinguish it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility scanning.

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 provides explicit use case contexts: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' However, it does not mention when not to use this tool or suggest alternative tools, so it lacks exclusions.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the list of return fields and the optional 'include_inactive' parameter, but does not disclose additional behavioral traits (e.g., authorization requirements or pagination). Given the rich annotations, the description adds moderate 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 two sentences with the main purpose front-loaded. Every sentence adds value with no waste.

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

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

For a simple tool with one optional boolean parameter and no output schema, the description covers purpose, return fields, and usage context comprehensively. No annotation contradictions.

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 single parameter 'include_inactive' is fully described in the input schema (100% coverage). The description does not add further meaning beyond what the schema provides, resulting in a baseline score of 3.

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

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

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

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies when to use the tool (before subscribing or unsubscribing) but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds that it returns schema details but does not disclose error handling, auth requirements, or rate limits. It does not contradict annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficiently communicates what the tool does.

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

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

With an output schema and clear annotations, the description covers retrieving database schema. Could explicitly state that it does not return records, but the term 'schema' implies that. Good overall.

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

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

Schema covers the single parameter with description. The tool's description adds no additional semantics beyond that, so baseline 3 is appropriate given 100% 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 gets a Notion database schema by ID, returning properties, field types, and configuration. It distinguishes from siblings like notion_get_page and notion_query_database by focusing on structure rather than 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?

The description implies use for retrieving database structure but does not explicitly contrast with siblings or provide when-not-to-use guidance. With multiple related tools, more explicit direction would help.

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 read-only, idempotent, and non-destructive nature. The description adds context about returning 'full properties, metadata, and content structure,' which enriches the behavioral understanding beyond annotations.

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

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

The description is a single, front-loaded sentence that immediately conveys the core action and output. No extraneous words.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description adequately covers what the tool does and returns. It could mention error scenarios (e.g., page not found, auth), but is generally sufficient.

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

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

Schema coverage is 100% and the description does not add new information about the `page_id` parameter beyond what the schema provides (UUID format). Reiterating 'by ID' is redundant but not harmful.

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 'Get a Notion page by ID,' specifying the verb (get), resource (page), and identifier (ID). It distinguishes from sibling tools like notion_list_pages or notion_query_database by focusing on a single page 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 when to use (when you have a page ID), but does not explicitly state when not to use or provide alternatives. With siblings like notion_list_pages and notion_search, some guidance on choosing the right tool would be beneficial.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds that it returns titles and IDs but does not detail pagination behavior or scope limitations beyond 'accessible pages'. 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 sentences with no wasted words. First sentence covers purpose, second explains output. Front-loaded and efficient.

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

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

Given the simplicity of the tool, good annotations, and presence of output schema, the description is mostly complete. It could mention pagination implications but the schema covers parameters. Sufficient for a list tool.

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

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

Schema coverage is 100% with descriptions for both page_size and start_cursor. The tool description does not add any additional meaning beyond the schema, maintaining the baseline.

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

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

Description clearly states the verb 'list' and resource 'all accessible pages in your Notion workspace'. It distinguishes from sibling tools like notion_search (search) and notion_get_page (single page) by focusing on listing all accessible pages.

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 explicit guidance on when to use this tool versus alternatives like notion_search or notion_query_database. The description does not provide any context for selecting this tool over siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds minimal extra behavioral context: it mentions returning matching rows. No further details on pagination, rate limits, or auth requirements are given, but annotations cover safety profile.

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

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

The description is two sentences long, front-loaded with the core purpose, and contains no redundant information. Every sentence earns its place.

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

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

Given the presence of a full output schema and rich annotations, the description adequately covers the tool's behavior. It mentions return type and use case. Pagination is handled by schema parameters; no additional explanation 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 description coverage is 100%, and the description adds contextual example (e.g., status='Done') but does not explain parameters beyond what the schema provides. 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 queries a Notion database with filters and sorting, using specific verb and resource. It distinguishes itself from siblings like notion_list_pages by emphasizing filtering and sorting capability.

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 filtered/sorted queries but does not explicitly state when to use this tool over alternatives like notion_list_pages or notion_search. No explicit when-not or alternatives are provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that results include titles, IDs, and types, which is useful but does not substantially extend behavioral understanding beyond the annotations. It does not mention pagination or rate limits, but given the strong annotation coverage, a score of 3 is appropriate.

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

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

The description is extremely concise: two sentences that together clearly communicate the tool's purpose and output. Every word is necessary, and the structure is front-loaded with the action. No wasted 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?

Given the tool has an output schema, the description need not fully detail return values. It effectively communicates the key return fields (titles, IDs, types). However, it does not mention pagination (start_cursor) or result limits, which are captured in the schema. With rich annotations covering safety and a clear schema, the description is sufficiently complete for most use cases. A minor gap prevents a 5.

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

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

Schema coverage is 100%, so the schema already documents all four parameters with descriptions. The description adds no additional meaning beyond aligning the 'query' parameter with 'keyword'. It does not elaborate on filter options or pagination behavior. Per guidelines, baseline 3 is correct when schema coverage is high and description adds minimal extra value.

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

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

The description clearly states the tool's function: searching a Notion workspace by keyword, and specifies the return types (titles, IDs, types). This effectively distinguishes it from sibling tools like notion_get_page or notion_list_pages, which are more specific retrieval operations.

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 no guidance on when to use this tool versus alternatives. With many sibling tools for specific Notion operations (notion_get_page, notion_query_database, etc.), an agent would benefit from explicit context on when search is appropriate and when a more targeted tool is preferred. This is a notable gap.

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?

All annotations are false (readOnlyHint, destructiveHint, etc.), which is appropriate for a write operation. The description adds important behavioral context: rate-limited, free, doesn't count against tool-call quota, and that the team reviews daily. No contradiction with annotations.

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

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

The description is concise (three sentences) and well-structured. The first sentence states the core purpose, followed by usage guidance and constraints. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (feedback type, optional context object, rate limits, quota impact), the description covers all necessary aspects: rationale, what to include/exclude, team process, and limitations. No output schema is needed; the feedback is simply sent.

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 beyond the schema by explaining the purpose of each type (e.g., 'bug = something broke') and reinforcing the guidance on message content (be specific, 1-2 sentences, 2000 chars). This aids an agent in populating parameters correctly.

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: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes itself from sibling tools, which are focused on research, queries, subscriptions, etc., making this the only tool for submitting feedback.

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

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

The description explicitly specifies when to use the tool: for bugs (wrong/stale data), feature requests, data gaps, or praise. It also provides guidance on what not to include (end-user prompts) and mentions rate limits (5 per day per identifier). This gives clear context for choosing this tool 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?

Description adds significant behavioral context beyond annotations: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). No contradictions with readOnlyHint, idempotentHint.

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

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

Concise paragraph with numbered list of use cases. Every sentence adds value without repetition. Front-loaded with 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 lacking an output schema, the description fully explains return values (top tools, packs, volume) and provides caching and data source details. Sufficient for a tool with one optional parameter.

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

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

Schema coverage is 100% for the window parameter. Description adds semantic guidance: shorter windows show what's hot, longer show steady-state. This enhances understanding beyond the enum options.

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

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

Clearly states it returns top tools, packs, and call volume with specific time windows. Distinguishes from sibling tools like discover_tools by focusing on trending usage by AI agents.

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 three explicit use cases (discovery, confirmation, alignment). Does not list exclusions or alternatives, but the context is clear enough for an AI agent to decide 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes well beyond by detailing the algorithms (monotonicity violations, partition-sum checks, Jaccard similarity anchor, placeholder filtering, and fill check with realizable edge). It also explains failure conditions (low similarity, placeholder fraction >20%, realizable_edge_pp ≤ 0). No contradictions with annotations.

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

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

The description is lengthy but well-structured, starting with a requirement (no args fails), then explaining modes, algorithms, and edge cases. Every sentence provides useful information. It could be slightly more compact, but it's efficient given the complexity.

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

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

No output schema exists, so the description must explain return values, which it does: opportunities[] with fields like gap_pp, suggested_trade, reasoning, and partition_check in event mode. It also covers edge cases (placeholders, low similarity) and references polymarket_fill_risk for custom sizing. The description is comprehensive for a complex tool.

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

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

Schema coverage is 100% with both 'event' and 'topic' described. The description adds context by explaining what slugs look like (e.g., 'fed-decision-may-2026') and that topic is a seed question. It also recommends event mode for specific markets, adding value beyond the schema. Baseline is 3, but the additional context justifies a 4.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and specifies that calling with no args fails. This is a specific verb+resource with clear differentiation from sibling tools.

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

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

The description provides explicit guidance on when to use each mode: event for a specific market, topic for cross-event scanning. It gives example inputs and explains that cross-event mode catches patterns single-event misses. It also warns that calling with no args fails. However, it doesn't explicitly state when not to use this tool vs. alternatives like polymarket_fill_risk, though that tool is mentioned for custom sizing.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral details: caching (1h at KV level), response structure (by_segment, diagnostics), edge calculation methodology (Kelly, slippage), and tradeable-edge knobs. No contradiction with annotations.

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

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

Well-structured with sections for segments, knobs, and response. However, it is quite verbose; many details could be summarized more concisely without losing clarity. Slightly too long for quick parsing.

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

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

Despite no output schema, the description fully explains the response structure, including by_segment segments, diagnostics, and caching. All 9 parameters are covered in schema. The tool's behavior is comprehensively described.

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%; every parameter has a description. The description adds context for knobs (e.g., 'Tradeable-edge knobs' section) but does not fundamentally add meaning beyond what the schema provides. 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?

Explicitly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. The verb 'scan' and resource 'Polymarket markets' are clear. It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on Pipeworx disagreement.

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

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

States it's built for 'what should I bet on today' and that agents discover opportunities without paging. However, it does not explicitly state when not to use it or provide comparisons to alternative tools like 'bet_research' or 'polymarket_arbitrage'.

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. Description adds rich behavioral detail: explains snapshot-based nature, gaps from cache misses, decay computed from daily closes (not intraday), and the structure of tracked/expired arrays. No contradiction with annotations.

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

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

Description is packed with information but well-structured: starts with purpose, then args, then response breakdown, then limitations. Every sentence adds value. Slightly long but justified by 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?

No output schema, so description fully explains return fields (tracked, expired, snapshot_dates). Also covers limitations like 60-day TTL and daily-only decays. Complete for a telemetry tool with time-series data.

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

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

Both parameters have schema descriptions (100% coverage). Description reinforces defaults (days default 14 max 30, window default 1wk) but does not add significant new semantic info beyond schema. Response explanation is helpful but not parameter-specific.

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

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

Clear statement of purpose: telemetry on edge persistence and decay. Distinct from sibling 'polymarket_edges' which likely provides current edges vs. historical tracking. Description explicitly answers 'how long has this edge existed and is it shrinking?'.

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 context on when to use: distinguishes between fresh and old edges. Implies use when edge age matters for trade quality. Does not explicitly list when not to use or name alternatives, but the sibling tool list and context hint at 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond these: it explains the verdict (clean|degraded|cannot_fill), the risk of partial fills, forced directional risk, and return fields like slippage_pp and thin_legs. This is rich 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 with bold and capitalization for emphasis, and it front-loads the purpose. It is somewhat lengthy but every sentence adds necessary detail given the tool's complexity (two modes, many return fields). Some redundancy could be trimmed, but it remains efficient.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is comprehensive. It explains the modes, all return fields (top_of_book, vwap_fill_price, etc.), the verdict, and risk warnings. The lack of an output schema is mitigated by the detailed description of outputs.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning: it clarifies the dual-mode usage for market vs event, explains the side default behavior in basket mode, and details the interpretation of size_usd for single-market buys/sells vs basket settlement. This adds significant value.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and the title 'Polymarket Fill Risk' reinforces the purpose. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying it is for checking fill risk before acting on 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.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional positions). This is exceptional guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing behavioral traits: compatibility_warning conditions (non-equivalent bet shapes or semantically unrelated events), temporal_alignment check, and skipped_cross_type/cross_subtype counters. It explains when spreads are meaningless, providing rich context for safe usage.

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 (modes, response, safety fields) and each sentence adds value. It is somewhat verbose but justified by the complexity of the tool. It could be slightly more concise, but the front-loaded purpose and logical flow make it effective.

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

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

Given the tool's complexity and the absence of an output schema, the description covers the key aspects: response structure (leg-by-leg prices, top_spreads_pp), compatibility warnings, and temporal alignment. However, it lacks explicit details on the exact format or number of spread entries, which would enhance completeness.

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

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

Although the input schema has 100% coverage and lists parameters with descriptions, the tool description adds significant meaning: it explains the two modes, provides the full list of topic shortcuts with examples ('fed', 'btc', etc.), and clarifies that explicit parameters override the topic mapping. This context helps the agent understand valid inputs beyond schema types.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the function (calculating spreads), the two modes (topic shortcuts and explicit pairing), and distinguishes itself from sibling tools like bet_research or polymarket_arbitrage by focusing on cross-venue spreads.

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

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

The description provides clear usage context: two modes (topic for pre-mapped shortcuts, explicit for custom pairings). It explains when each mode is appropriate and includes important caveats like 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' However, it does not explicitly contrast with sibling tools or state when not 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe operations. The description adds value by explaining the scoping mechanism (by identifier) and the behavior of listing keys when no key is provided, which goes beyond annotation details.

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

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

The description is concise and well-structured, with the main purpose upfront and additional context in subsequent sentences. 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 rich annotations and complete schema, the description covers all necessary aspects: purpose, usage, scoping, and pairing with siblings. No gaps are evident.

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

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

Schema coverage is 100% with a clear description for the key parameter. The description reinforces the optional nature and listing behavior but does not add substantial new meaning beyond what the schema already provides.

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

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

The description clearly states the tool retrieves a specific value via key or lists all saved keys when key is omitted. It distinguishes itself from sibling tools like 'remember' and 'forget' by explicitly mentioning them in the pairing context.

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, such as looking up previously saved context without re-deriving it, and notes scoping to user identifier. However, it does not explicitly state when not to use it or provide alternative tools beyond remember/forget.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: mark_read updates read state affecting future calls, and it describes the returned fields. 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 three sentences, front-loaded with the main purpose, and every sentence adds value. No fluff.

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

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

No output schema exists, but the description explains what the tool returns (source, citation_uri, raw payload). It covers filtering, side-effects, and alternative use. For a 5-param tool with full schema coverage and strong annotations, this is sufficiently complete.

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

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

Schema coverage is 100% with descriptions for each parameter. The tool description adds context with an example filter type ('sec_8k') and clarifies the side-effect of mark_read (flags events as read, so next call shows newer ones). This goes beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns most recent alerts with specific fields (source, citation_uri, payload). The verb+resource is specific, though it does not explicitly differentiate from siblings like list_subscriptions or recent_changes.

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

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

The description mentions filtering options (type, since) and the mark_read flag for state management. It also notes that polling works and provides an alternative access method (GET endpoint). However, it lacks explicit guidance on when to use this tool vs alternatives, or when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: fans out to multiple sources, fallback from GDELT to GNews, USPTO soft-fail due to API sunset, and return structure (changes[] grouped by source, total_changes, citation URIs). No contradiction.

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

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

The description is concise yet comprehensive, front-loaded with example queries. Every sentence provides useful information without redundancy. The structure efficiently covers purpose, usage, source behavior, date formats, return format, and alternative tool guidance.

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 and only 3 required parameters, the description fully covers the tool's complexity: multiple data sources, fallback mechanisms, date format flexibility, return structure, and clear differentiation from sibling tools. No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. But the description adds substantial value: explains that 'since' accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'), clarifies that 'value' can be a ticker or CIK with example, and notes that 'type' is currently only 'company'. This goes well beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company over a time window, sourcing from SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes itself from the sibling tool 'entity_profile' by specifying that entity_profile should be used for static profiles regardless of window.

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 includes explicit example queries (e.g., 'what's new with X', 'latest on Y') and provides a direct alternative: 'Use entity_profile instead when you want the static profile'. This clearly guides when to use this tool versus 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 goes beyond annotations by detailing storage scoping (key-value pair per identifier), persistence differences (authenticated persistent, anonymous 24h), and pairing with recall/forget. No contradictions with annotations, which are consistent.

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 that are front-loaded with purpose, each sentence adding distinct value: purpose, usage guidance, and behavioral details. No wasted words.

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

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

Given the simple tool (2 params, no output schema, annotations present), the description fully covers what the agent needs: purpose, when to use, storage behavior, and relationship to sibling tools. Complete.

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

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

Schema coverage is 100% and already describes both parameters. The description adds helpful examples for key (e.g., 'subject_property') and clarifies value as 'any text', which adds slight extra meaning.

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

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

The description clearly states 'Save data the agent will need to reuse later' using a specific verb and resource. It distinguishes itself from sibling tools like recall 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?

Explicitly advises when to use the tool ('when you discover something worth carrying forward') and explains when not to use it by pairing with recall and forget. This provides clear usage context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: it cascades through multiple lookup endpoints, returns specific fields (including citation URIs), and auto-disambiguates company names. This provides deep transparency 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 well-structured with a clear flow: core action, examples, supported types. It is informative without unnecessary repetition. However, the sentence about cascading through endpoints and replacing lookups is slightly redundant, and the description could be slightly more concise.

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

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

Given no output schema, the description adequately explains return values for each type and provides input examples. It covers the key contextual needs for an agent to use this tool. A minor omission is the lack of error handling or what happens if the entity is not found, but overall it is complete enough.

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 significant value by explaining what each entity type returns, what inputs are accepted (ticker, CIK, name for company; brand/generic for drug), and that company inputs are auto-disambiguated. This goes beyond the schema's simple parameter 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: resolve a user-spoken name to a canonical/official identifier. It provides specific verb phrases ("What's the ticker for…") and distinguishes from siblings by positioning itself as the first tool to use when needing an ID. The supported entity types and their return values are explicitly described.

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

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

The description explicitly says "Use FIRST whenever you have a name but need an ID," providing clear when-to-use guidance. It also notes that using resolve_entity replaces 2-3 manual lookups. However, it does not explicitly state when not to use the tool or mention alternative tools for comparison, slightly reducing the score.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds specific behavioral details: it probes each entity via 'ai_visibility_check', ranks by score, and returns a list with 'score, confidence, signal density per entity.' No contradictions.

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

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

The description is two sentences, front-loaded with purpose. It is somewhat long but every part adds value (purpose, method, use case, return info). Could be slightly more concise but remains efficient.

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

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

Given no output schema, the description covers return fields (score, confidence, signal density). It also addresses parameter constraints and optional fields. However, it does not explain pagination or error handling, but given the tool is essentially a multi-call wrapper, these gaps are minor. Complete enough for its complexity.

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

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

Schema description coverage is 100%, but the description adds significant semantic value: it specifies that 'entities' must be 2-8 items and the first is the 'subject', explains supported models and API key requirement for 'anthropic', and clarifies that 'context' disambiguates common names. These details go well beyond the schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compares, probes, ranks, surfaces), the resource (AI visibility across entities), and differentiates from the sibling tool 'ai_visibility_check' by explicitly mentioning multi-entity 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 provides a concrete use case: 'competitive AI-marketing audits' and gives an example question. It implies the tool is for comparing multiple entities but does not explicitly state when not to use it or mention the alternative single-entity tool. Lacks exclusion criteria.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: fans out to two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. No contradiction.

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

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

Description is detailed but front-loaded with core purpose. Every sentence adds value, though slightly verbose. Could be tightened without losing information.

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

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

No output schema, so description fully explains return structure: summary block fields, per-advisory detail, links, alternative versions. Also covers error behavior (partial failures, timeout). Complete for a composite multi-source 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 100% with clear descriptions. Description adds context: package name accepts scoped packages, version defaults to latest. This enhances understanding beyond schema.

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

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

The description clearly states it is a composite check for npm packages, listing specific aspects (license, advisories, version history, bundle size, etc.). It distinguishes from siblings by noting the NPM-only scope and directing other ecosystems to deps.dev directly.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clarifies NPM-only and mentions alternative for other ecosystems.

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

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

The description adds significant behavioral detail beyond the annotations, including the embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), output fields (character offsets and similarity scores), and the 200K char limit with truncation flagging. This context is not available in the annotations and fully informs the agent.

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

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

The description is a single, well-structured paragraph with no excess verbiage. The first sentence states the core purpose, followed by practical usage, output details, pairing information, and technical specifics. Every sentence serves a purpose and is front-loaded with the most critical information.

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

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

The tool has no output schema, but the description thoroughly explains the return type (top-N passages with offsets and scores), the embedding details, and the input constraints. It also covers when to use the tool and how it integrates with another tool. Given the tool's low complexity (3 parameters), this description is fully adequate for an agent to use correctly.

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

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

Schema coverage is 100%, but the description enriches the parameter meanings beyond the schema: it explains that 'text' is a previously fetched document, provides example queries for 'query', and clarifies the default and range for 'limit'. The examples and usage context add value, though the schema descriptions were already solid.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific verbs like 'semantic search' and 'pass the text... get back the top-N passages.' It distinguishes itself from siblings by explicitly naming a paired tool (ask_pipeworx_grounded) and contrasting its use case with other tools.

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

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

The description provides explicit guidance on when to use this tool ('when the record is too big to cram into the prompt') and mentions an alternative approach ('Pairs with ask_pipeworx_grounded'). It also notes the 200K character cap and truncation behavior, helping agents decide if the input is suitable.

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 write operation, idempotent, and non-destructive. The description adds context: returns new subscription id, limitations on anonymous accounts, delivery channel constraints (SMS cap, webhook auto-disable). No contradiction with annotations, but idempotency is not explicitly addressed.

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 and front-loaded with the purpose. While it is lengthy, every sentence adds essential information. It could be slightly more concise, but overall effective.

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

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

Given the complexity of multiple subscription types and delivery channels, the description covers prerequisites, return value, and limitations. It lacks mention of the unsubscribe counterpart, but alternatives are available as sibling tools. Complete enough for an agent.

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

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

Schema coverage is 100%, but the description adds significant value with detailed examples for each subscription type and delivery options, including constraints like phone verification and webhook signing. This far exceeds 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 the tool creates a subscription to a live-data event stream and returns the subscription ID. It distinguishes from siblings like unsubscribe and list_subscriptions by specifying it creates a new proactive monitoring subscription.

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 create a monitoring subscription) and provides prerequisites (Pipeworx OAuth account). It does not explicitly state when not to use, but the detailed examples for each type and delivery channels offer clear guidance.

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

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

The description details the tool's behavior: it returns categorized example questions with tool shapes, draws from a live catalog, and supports an optional topic filter. Annotations already indicate read-only and idempotent, so the description adds valuable context without contradiction.

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

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

The description is informative but somewhat verbose, including an exhaustive list of categories. While front-loaded with example queries, it could be condensed without losing meaning. Every sentence serves a purpose, but length slightly reduces conciseness.

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

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

Given the simple tool (one optional parameter, no output schema), the description fully explains the return format, usage scenarios, and when to call. It lacks details on error handling but otherwise covers needed context adequately.

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 description for 'topic' is already clear (100% coverage), and the tool description adds examples and usage context (e.g., 'omit for full spread'). This complementary information enhances understanding without redundancy.

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

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

The description clearly states the tool's purpose: returning category-bucketed example questions for onboarding. It uses specific verbs like 'returns' and 'focuses', and distinguishes itself from siblings by positioning as the first tool to use when unfamiliar with Pipeworx.

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

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

The description explicitly advises using this tool first when unsure what Pipeworx can do or to learn meta-tool calls. It provides guidance on calling with or without the topic parameter. However, it does not explicitly state when not to use it, but the context is clear.

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

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

Describes the row is 'deactivated (not deleted)' and historical events remain, providing useful behavioral context beyond annotations. No contradiction with annotations (destructiveHint=false, idempotentHint=true).

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

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

Two sentences, no filler. Key information is front-loaded and each 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 single-parameter tool with no output schema, the description explains the effect (deactivation) and its impact on historical data, making it complete.

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

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

Schema covers 100% of parameter descriptions. The description adds 'by id' but does not add new meaning beyond the schema's 'id' description. 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 action ('Cancel a subscription') and the resource ('by id'). It directly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly notes ownership enforcement: 'you can only cancel your own subscriptions.' This gives a clear when-to-use and when-not-to-use condition, though it doesn't name explicit alternatives like 'contact support'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: v1 status, supported claim domain (company-financial), data source (SEC EDGAR+XBRL), and the return format (verdict, value with citation, delta). No contradictions with annotations.

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

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

The description is front-loaded with example intents, followed by purpose, scope, and output. It could be slightly more concise (e.g., listing return fields could be deferred to an output schema), but it remains 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?

Given the tool has only one parameter and no output schema, the description covers purpose, usage, domain, return values, and efficiency benefits. It provides enough context for correct invocation without requiring additional documentation.

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

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

The input schema has 100% coverage with a good description for the 'claim' parameter. The tool description adds extra context about what kinds of claims are supported (company-financial) and that input is natural language, enhancing the schema's meaning.

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

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

The description provides a clear, specific verb-resource pairing: 'natural-language claim verification against authoritative sources.' It distinguishes from siblings by focusing on company-financial claims using SEC EDGAR+XBRL, and the examples cover the full range of user intents (fact check, verify, confirm/refute).

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 ('whenever the agent needs to check whether something a user said is factually correct') and notes it replaces multiple sequential calls. However, it does not explicitly state when not to use it (e.g., for non-financial claims), though the domain is clearly scoped.

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