Nosdeputes Fr

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

The annotations already declare readOnlyHint=true, so the agent knows this is safe. The description adds significant transparency: it explains the routing mechanism across 1,423+ tools, fills arguments, returns structured answers with stable citation URIs. It doesn't discuss error handling or limits, but the behavioral disclosure is strong 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 a single paragraph that fronts the most critical information ('PREFER OVER WEB SEARCH'). Every sentence adds value: preference, sources, mechanism, use cases, examples. It could be slightly more structured (e.g., bullet points) but is not verbose and remains clear and actionable.

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 input schema (one string parameter) and no output schema, the description provides comprehensive context: the tool's role, when to use it, what sources it covers, how it processes questions (routing, argument filling, citation generation), and the answer format (structured with pipeworx:// URIs). It leaves no major gaps for effective agent use.

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

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

Schema coverage is 100% with a single parameter 'question' described as 'Your question or request in natural language'. The description adds context about the types of questions (factual, real-world) and examples, but the parameter itself is straightforward and the schema already covers its purpose. No additional syntax or constraints are needed.

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: routing questions to authoritative sources and returning structured answers with citations. It explicitly says 'PREFER OVER WEB SEARCH' and lists many example data sources and query types, making the purpose unmistakable and distinguishing it from sibling tools.

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

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

The description provides explicit guidance on when to use this tool (factual questions about real-world entities, events, numbers) and implicitly when not (subjective/creative queries). It gives concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K' and explicitly contrasts with web search, fulfilling the 'when-to-use vs alternatives' criterion.

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

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

Annotations declare readOnlyHint=true, and description confirms read-only behavior. Adds detail on data provenance (SEC EDGAR, FAERS) and output format (paired data + citation URIs), beyond what annotations provide.

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

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

Description is informative but slightly verbose (3 sentences + parenthetical examples). Well-structured with clear use-case triggers and data sources, though could trim redundant phrasing.

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

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

Covers all necessary aspects: supported entities, data sources, return format (paired data + URIs), and efficiency gain. No output schema, so description compensates by explaining output.

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

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

Schema coverage is 100% (baseline 3). Description enriches both parameters: explains 'type' enum values with examples and clarifies 'values' format (tickers vs drug names, min/max count).

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

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

Clearly states the verb 'compare' and resource 'companies or drugs', with specific data sources (SEC EDGAR, FAERS) and examples. Distinguishes from siblings like entity_profile by focusing on side-by-side 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?

Explicitly lists trigger phrases ('compare X and Y', 'X vs Y') and use cases (tables/rankings). Mentions efficiency gain (replaces 8–15 calls), but lacks explicit when-not or alternatives to other tools.

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

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

The description explains that the tool returns 'top-N most relevant tools with names + descriptions,' which adds behavioral context beyond the readOnlyHint annotation. There is no contradiction with annotations, and the description makes the tool's non-destructive, informational nature clear.

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

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

The description is a single paragraph with clear sentences and no unnecessary words. It includes a long list of example domains, which is informative but slightly verbose. Overall, it is well-structured and front-loaded with the core purpose.

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

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

For a simple, read-only discovery tool with two parameters and no output schema, the description covers all necessary aspects: what it does, when to use it, how to use it, and what it returns. It provides sufficient context for an AI agent to invoke the tool correctly.

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

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

The input schema already provides 100% coverage with clear descriptions for both parameters ('query' and 'limit'). The description restates the query parameter concept but adds no new semantic details beyond what is in the schema. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools (specific tools like entity_profile) by positioning itself as a discovery mechanism. The verb 'find' combined with 'tools' and the task description is direct and unambiguous.

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

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

The description explicitly instructs: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists concrete example domains (SEC filings, FDA drugs, etc.), providing clear context for 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?

Annotations already declare readOnlyHint=true. Description adds specific return content (SEC filings, revenue, patents, news, LEI with citation URIs). No mention of pagination or limits, but overall transparent.

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 main purpose and provides detailed but relevant information. Slightly lengthy but all sentences earn their place. Could be slightly more concise.

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

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

No output schema, so description fully explains return values by listing categories. Covers all needed context for a profile-gathering 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%. Description adds context: type only supports 'company', value can be ticker or CIK with examples, and notes that names require prior resolution via resolve_entity. This adds value beyond schema.

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

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

Description clearly states 'Get everything about a company in one call' and lists the resources covered (SEC filings, fundamentals, patents, news, LEI). It effectively distinguishes from siblings 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 provides use cases (queries like 'tell me about X') and when not to use (if only name, use resolve_entity first). Also notes it replaces calling 10+ pack tools, giving 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?

Annotations already indicate non-read-only nature (readOnlyHint=false). Description adds context about clearing sensitive data, but doesn't detail irreversibility or permissions.

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

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

Two sentences, front-loaded with action, then usage context. No unnecessary words.

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

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

For a simple delete tool with one parameter and no output schema, the description fully covers purpose, usage context, and sibling relationships.

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 describes 'key' as 'Memory key to delete'. Description adds no further meaning beyond schema, and coverage is 100%.

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', specifying the verb and resource. It distinguishes itself from siblings 'remember' and 'recall' by name.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also names alternatives 'remember' and 'recall'.

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 set readOnlyHint=true, indicating a safe read operation. The description implies reading a profile, consistent with annotations. No additional behavioral traits (e.g., rate limits, caching) are disclosed, but the annotation provides baseline 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?

A single 8-word sentence that conveys the core purpose without any fluff. Every word 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?

The description does not explain what a 'deputy profile' contains (e.g., name, party, district) nor differentiate from 'entity_profile'. With no output schema, the agent has little to infer the return value. The purpose is clear but incomplete 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 50%: only 'slug_or_id' has a description, which the description echoes. The 'legislature' parameter lacks description in both schema and description. The description adds no new meaning beyond the schema for the covered parameter and ignores the uncovered one.

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 'Deputy profile by slug or numeric id' specifies the resource (deputy profile) and the means of identification (slug or id), clearly distinguishing it from list-like tool 'list_deputies'. However, it does not differentiate from 'entity_profile', which may overlap.

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

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

No guidance on when to use this tool versus alternatives like 'entity_profile' or 'list_deputies'. The description lacks any context about appropriate usage scenarios or prerequisites.

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 readOnlyHint annotation already indicates a safe read operation. The description adds minimal behavioral context beyond 'list sitting deputies'; it does not disclose pagination, ordering, or data freshness. However, it does not contradict the annotation.

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, concise sentence that front-loads the core action and optional filters. It could be slightly improved by noting that the 'active' parameter defaults to true, but overall it is efficient and wastes no words.

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

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

Despite having 4 optional parameters and no output schema, the description fails to explain what the output contains (e.g., a list of deputy objects with fields like name, party, group) or behavior when no filters are provided. This leaves agents guessing about the return format.

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

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

Schema description coverage is 100%, so the schema fully documents all 4 parameters. The description's mention of 'filtered by group or département' adds no new meaning beyond the schema; it does not explain parameter interactions (e.g., combining filters). 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 uses a clear verb-resource combination, 'List sitting deputies', and explicitly mentions optional filters (group or département), which distinguishes it from sibling tools like 'get_deputy' (single deputy) and 'list_groups' (groups only).

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

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

The description implies usage for listing deputies with optional filters but provides no explicit guidance on when to use this versus alternatives (e.g., get_deputy for a specific deputy, search_interventions for related content). No exclusions or when-not-to-use info.

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, indicating a read operation. The description adds no additional behavioral context (e.g., pagination, scope of results). 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?

The description is a single short sentence, making it concise. However, it lacks substance and does not effectively convey the tool's function, so it is only minimally adequate.

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 (list operation with one optional param) and no output schema, the description should clarify what the tool returns or how it filters. It does not, leaving the agent with insufficient information.

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

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

Schema coverage is 0% (no parameter descriptions) and the description does not explain the 'legislature' parameter. The description should compensate for low coverage but fails to clarify parameter meaning or usage.

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

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

Description 'Political groups in the assembly' is a noun phrase rather than an action statement. It does not specify a verb like 'list' or 'retrieve', making the tool's purpose vague. It fails to clearly state what the tool does.

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

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

No guidance is provided on when to use this tool versus its siblings (e.g., list_deputies, list_votes). No contexts, prerequisites, or alternatives are mentioned.

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

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

Annotations already declare readOnlyHint=true, which covers the read-only nature. The description implies a read operation but adds no additional behavioral context such as pagination, rate limits, or data freshness. With annotations present, this is adequate but not enhanced.

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?

At three words, the description is very concise and front-loaded. However, it is under-specified, making it less informative than it could be while still 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?

The tool has three optional parameters and no output schema. The description does not explain what a 'vote' record contains, how to use parameters effectively, or what the response looks like. It lacks completeness 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 description coverage is 67% (two of three parameters have descriptions). The tool description adds no parameter-level information beyond the schema; the undocumented 'legislature' parameter remains unexplained. The description does not compensate for the gap.

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 'Recent recorded votes.' is nearly tautological with the tool name 'list_votes', adding only the qualifier 'recent' but not specifying scope or distinguishing clearly from siblings. It does not indicate what kind of votes or how recent.

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

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

No guidance on when to use this tool versus alternatives like list_deputies or search_interventions. No exclusions or context for effective use 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 indicate this is not read-only. The description adds behavioral context: it's rate-limited 5/day, free, and doesn't count against quota. It also mentions the team reads digests daily and feedback affects roadmap, though more detail on processing could be added.

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

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

The description is moderately detailed but efficiently structured: purpose first, then usage guidelines, then constraints. Each sentence adds value, though it is slightly longer than minimal.

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

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

Covers key aspects: purpose, when to use, what to avoid, constraints (rate limit, quota), and team response. Lacks mention of anonymity or response time, but is adequate for a feedback 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 detailed descriptions. The tool description adds extra guidance (e.g., 'Describe the issue in terms of Pipeworx tools/packs'), complementing the schema 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: to send feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes from sibling tools by focusing on feedback collection, which is a distinct function not covered by 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?

Explicitly specifies when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). Includes rate limits and quota information, providing clear usage boundaries and alternatives like other tools.

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

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

The description adds significant value beyond the readOnlyHint annotation by explaining scoping (anonymous IP, BYO key hash, account ID) and the behavior of listing all keys when the key argument is omitted. It fully discloses the tool's read-only nature and data retrieval behavior.

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

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

The description is highly concise (4 sentences) and front-loaded with the main action. Every sentence adds essential information: purpose, usage, scoping, and pairing with siblings. 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 simple input schema (one optional parameter, no output schema), the description thoroughly covers purpose, usage context, behavioral traits, and relationships to sibling tools. It is complete 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?

With 100% schema description coverage, the description still adds meaningful context by explaining the effect of omitting the key (list all keys) and providing examples of stored values (ticker, address, notes). This enriches the schema's basic parameter description.

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

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

The description clearly identifies the tool's action (retrieve or list) and resource (saved memory via remember), and distinguishes it from siblings like remember and forget. It specifies the verb, resource, and scope, making it easy for an agent to understand what the tool does.

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

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

The description provides explicit use cases (look up context like tickers or notes) and pairs with remember/forget, but does not explicitly state when not to use this tool versus alternatives other than implying listing keys when argument is omitted. It offers clear context but no 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?

The description discloses that the tool fans out to multiple sources in parallel, explains the 'since' parameter syntax (ISO dates and relative shorthands), and specifies the return format (structured changes, total_changes count, pipeworx:// URIs). These details go beyond the readOnlyHint annotation, providing useful behavioral context.

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

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

The description is two sentences, front-loaded with purpose and followed by details. No unnecessary words. Every sentence provides 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?

Given the tool's moderate complexity (3 params, no output schema, minimal annotations), the description covers all necessary aspects: use cases, input formats, data sources, and output structure. It is self-contained and sufficient for an AI 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 coverage is 100%, but the description adds significant value: it explains the 'since' parameter's relative shorthand formats ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring. It also clarifies 'value' accepts tickers or CIK numbers with an example. This extra context aids correct invocation.

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 recent changes for a company over a specified time window, including example queries. It specifies the data sources (SEC EDGAR, GDELT, USPTO) and output structure (structured changes, count, citation URIs), fully distinguishing it from sibling tools like compare_entities or search_interventions.

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

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

The description provides explicit usage examples ('what's happening with X?', 'any updates on Y?', etc.) and a use case ('monitoring for changes'). While it does not list alternative tools, the examples make the intended use clear. No misleading 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?

Goes beyond annotations by detailing persistence behavior (authenticated vs anonymous sessions, 24-hour retention) and scoping by identifier, which is critical for understanding tool behavior.

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

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

Four sentences, each adding value: main purpose, usage context, storage details, and companion tools. Front-loaded and 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 2-parameter schema and no output schema, the description fully covers what an agent needs: purpose, when to use, how persistence works, and related tools.

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

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

The input schema already provides good descriptions for both parameters (key and value) with examples, and coverage is 100%. The description adds no new parameter-level information beyond what schema offers.

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

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

The description uses specific verbs and resource ('Save data the agent will need to reuse later') and provides concrete examples (resolved ticker, target address), clearly distinguishing from sibling tools like recall and forget.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') with examples, and mentions pairing with recall and forget. While no explicit when-not, the context is clear enough.

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

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

The description adds behavioral detail beyond the readOnlyHint annotation by explaining what IDs are returned and that it produces citation URIs. It does not mention error cases or rate limits, but for a read-only lookup this is adequate.

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

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

The description is a single paragraph of four sentences, front-loading the purpose and providing examples. It is efficient but could be slightly more concise by merging related points.

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

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

The description covers the tool's purpose, usage context, and return values (IDs + URIs) despite no output schema. However, it lacks information on error handling or missing entities, which slightly reduces 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?

The schema already describes both parameters with 100% coverage, but the description adds value with concrete examples (e.g., 'Apple' → AAPL/CIK) and clarifies the output IDs, making parameter usage clearer.

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

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

The description specifies a clear action ('Look up the canonical/official identifier'), a specific resource ('company or drug'), and distinguishes from siblings by stating it replaces multiple lookups and should be used before other tools needing identifiers.

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 when-to-use guidance ('when a user mentions a name and you need the CIK...') and explicitly states to use it before other tools. It does not discuss when not to use or alternative tools, but the context is well-defined.

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 is consistent with the 'readOnlyHint' annotation, indicating a read-only operation. It adds the term 'full-text' suggesting advanced search capabilities, but does not elaborate on behavior like pagination, result limits, or ordering. Given the annotation already covers safety, the description provides moderate additional 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?

A single, short sentence that immediately conveys the tool's purpose. No extraneous information; every word is necessary.

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

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

Given the tool has 6 parameters (one required) and no output schema, the description is under-specified. It omits details on result format, pagination, or default behavior. A search tool typically benefits from mentioning sorting, result size, or how to interpret 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?

With 67% schema description coverage, the schema partially describes parameters like 'limit', 'date_to', 'date_from', and 'deputy_slug'. However, 'query' (required) and 'legislature' lack descriptions in the schema, and the main description does not clarify their semantics. The description adds no parameter context 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 'Full-text search across debate contributions' clearly identifies the verb 'search' and the resource 'debate contributions'. It distinguishes this tool from siblings like 'search_questions' and 'entity_profile', making the purpose unmistakable.

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

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

The description provides no guidance on when to use this tool versus alternatives such as 'search_questions' or 'recent_changes'. No when-to-use, when-not-to-use, or prerequisites are mentioned.

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

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

Annotations indicate readOnlyHint=true, so the tool is safe. The description adds minimal behavioral context (mentioning 'written or oral questions') but doesn't conflict 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 extremely short but lacks substance, failing to convey necessary information. It is under-specified rather than 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 5 parameters, no output schema, and no usage guidance, the description is completely inadequate. It does not help an agent select or 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 coverage is only 20% (only 'type' has description). The description references 'written or oral questions' which loosely maps to the 'type' parameter, but other parameters like query, limit, deputy_slug, legislature are unexplained.

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 'Written or oral questions.' is vague and lacks a verb, so the tool's action (searching) is only implied by the name. It does not clearly state what the tool does.

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

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

No guidance is provided on when to use this tool versus siblings like search_interventions. The description gives no context for optimal usage.

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

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

The description discloses that the tool is read-only (consistent with annotations) and explains its internal process (replaces 4-6 calls), limitations (v1 supports only company-financial claims), and output structure (verdicts, citations). This goes well beyond the annotations.

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

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

The description is well-structured and concise, covering essential details. It includes examples and explanation of what it replaces, but could be slightly more terse without losing clarity.

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

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

Given the tool's complexity (replacing multiple manual steps) and lack of output schema, the description provides full transparency on verdict types, citation format, and scope. It is comprehensive and leaves few questions unanswered.

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 'claim' has a schema description with examples. The tool description adds natural-language examples and clarifies usage, enhancing the schema's meaning. Schema coverage is 100%, so baseline is 3, but the added context earns a 4.

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

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

The description clearly states the tool's purpose: fact-check or validate a natural-language claim against authoritative sources. It specifies that it supports company-financial claims via SEC EDGAR + XBRL, distinguishing it from sibling tools that handle other domains.

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

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

The description explicitly says when to use the tool, providing example user queries and stating it is for checking truth claims. However, it does not mention alternatives or when not to use it, leaving some ambiguity.

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