proofite

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

Annotations already show readOnlyHint=false, so mutation is expected. The description adds valuable behavioral context: the server can auto-discover feeds from site addresses, error messages are precise, and the tool is idempotent (per annotation). This goes beyond what annotations provide. 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 (two sentences) and front-loads the main action. Every sentence adds value, no fluff. Could be slightly more structured but is well within good practice.

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 parameter schema (2 mandatory fields, no output schema), the description is complete enough. It covers the main purpose, the extra discovery feature, error behavior, and doesn't need to explain return values since there is no output schema to reference. Still, a note on what the tool returns (e.g., success confirmation) would be helpful but not essential.

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

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

Schema coverage is 100% and the description adds no new detail for the parameters beyond what the schema already states (e.g., url can be a site address). The description does mention auto-discovery, which maps to the url parameter, but adds no extra semantics for source_id. 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 it adds an RSS/Atom feed to a topic inbox, and even distinguishes it from similar tools like remove_feed. The added detail about accepting plain site addresses with automatic feed discovery adds significant clarity.

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 hints at when to use it (adding a feed to an inbox) and what happens on failure, but it does not explicitly say when not to use it or how it compares to add_web_search or other sibling tools. The usage guidance is implicit, not explicit.

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 discloses that this is a recurring daily monitor ('every day', 'standing-search') and that results go into a topic inbox. It explains the behavioral difference between 'news' and 'search' for the kind parameter. Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are consistent; the description adds value beyond annotations by clarifying the recurring nature and purpose.

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 wasted words. The first sentence establishes the core purpose (daily monitor, inbox destination), and the second sentence clarifies the kind parameter. Information is 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 3 parameters, no output schema, and annotations present, the description covers the core action, parameter behavior, and use cases. It could mention the expected return value (e.g., created monitor ID), but that is not required. Overall, it is sufficient 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 coverage is 100%, so baseline is 3. The description adds meaning: explains kind with 'kind "news" watches the news index, "search" the whole web' and query as 'as you would type it into Google'. These enrich the schema descriptions. source_id is already clearly described in schema. Overall, adds meaningful extra context.

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

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

Description clearly states 'Monitor a Google query every day and feed the results into a topic inbox', specifying the verb (monitor), resource (Google query), and outcome (feed into inbox). It distinguishes from sibling tool 'add_feed' by mentioning 'the standing-search way to follow a company ... that has no RSS feed'.

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 context for when to use: 'follow a company, a person, a law or a niche subject that has no RSS feed', implicitly contrasting with add_feed. It also explains the kind parameter. However, it does not explicitly state when not to use or list specific alternatives beyond the implicit contrast.

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 valuable behavioral context beyond the annotations: it explains that the input is processed by an AI editor that translates the free-form note into concrete adjustments (topic preferences, settings, deep-dive requests). This is a significant disclosure of how the tool works internally. The annotations already indicate non-destructive, non-read-only behavior; the description appropriately amplifies that with no contradictions.

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

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

The description is two sentences long with no wasted words. The first sentence front-loads the purpose and gives concrete examples, and the second explains the mechanism and places it in context ('the main way a person retunes their news feed by talking'). Every sentence and phrase 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?

For a tool with 3 well-documented parameters, no output schema, and clear annotations, the description is complete. It explains what kind of input is expected, what happens internally (AI editor translates into concrete adjustments), and how it fits into the broader system of feed tuning. No gaps in understanding remain for the 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?

The schema already provides 100% coverage of the three parameters with clear descriptions. The tool description does add meaning to the 'note' parameter by giving rich examples of acceptable plain-language formats, and explains the purpose of 'entry_id' and 'briefing_id' implicitly through the phrase about 'specific story' and 'which briefing.' However, with full schema coverage, a baseline of 3 is appropriate and the description's added value is marginal beyond the examples.

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

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

The description clearly states the verb 'correct' and the resource 'briefing' explicitly, and gives concrete examples of plain-language inputs. It distinguishes itself effectively from sibling tools like 'tune_topic' or 'rate_briefing_entry' by positioning itself as the main way to retune a news feed via conversational 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 provides clear context for when to use this tool — to give free-form, plain-language correction to a briefing. It does not explicitly list alternatives or when not to use it (for example, if the user wants to set a specific topic weight without natural language, they might use tune_topic instead), but the phrase 'main way a person retunes their news feed by talking' strongly implies this is the primary conversational interface.

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

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

Annotations already mark readOnlyHint=false and destructiveHint=false, so the bar is lower. The description adds the key semantic that this creates a container with its own email address and is the top-level 'add a subject' operation. It doesn't discuss failure modes or permissions, but for a create operation the core behavior is effectively disclosed.

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 filler. The first sentence delivers the core action; the second adds conceptual context and purpose. Front-loaded and economical.

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 two-parameter creation tool with no output schema and no nested objects, the description covers what the resource is, how it relates to the information diet, and what it can contain. It does not address duplicates or return values, but these are not required for a correctly-scoped create operation.

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

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

Schema description coverage is 100%, and the parameter descriptions are already specific (short name with real examples, optional brief with reader expectations). The description does not add parameter-level detail, so baseline 3 applies.

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

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

States the verb and resource explicitly: 'Create a new topic inbox'. Expands with concrete attributes (dedicated email address, can hold RSS feeds and monitored web searches), which clearly distinguishes it from siblings like add_feed and add_web_search. The closing phrase places it as the top-level action for adding a subject to an information diet.

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 phrase 'This is how you add a whole new subject to someone's information diet' provides clear context for when to use the tool. However, it does not name alternatives or exclusions; siblings like add_feed and add_web_search are not referenced, so the agent must infer routing from the resource description rather than explicit 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 destructiveHint=true and idempotentHint=true. The description adds value by clarifying what gets destroyed ('all its feeds, searches and collected content') and that the email address stops working. It also warns about irreversibility. No contradiction with annotations. Score 4 because while it adds good context, it doesn't mention any rate limits or authorization requirements.

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, zero waste. Each sentence earns its place: first states what it does and scope, second warns about what happens and irreversibility, third gives an alternative. No fluff.

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

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

Given zero output schema, the description doesn't explain what happens on success (e.g., return value). However, for a destructive action with idempotentHint=true, the behavior is fairly expected—the resource is gone. The description adequately covers the deletion scope and side effect (email stops). A brief note on return status could push to 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 baseline is 3. The description doesn't add meaning beyond what the schema provides for the single parameter (source_id). The schema itself documents the parameter well, referencing 'list_sources' for where to get the ID.

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

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

The description clearly states what the tool does with a specific verb ('permanently delete') and resource ('topic inbox'), and distinguishes it from the sibling tool 'update_source' by noting that this is the irreversible option. The title 'Delete a topic inbox' matches the description well.

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

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

Explicitly tells the agent when to prefer an alternative ('Prefer update_source with is_active false when in doubt'), which provides clear usage boundaries. The warning about irreversibility also guides the agent to use this tool only when certain.

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 openWorldHint=true. The description adds valuable behavioral context: sources are validated live, dead ones are dropped before the user sees them, and it returns proposals rather than directly adding sources. This goes beyond the annotations by explaining the validation process and output nature.

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 (4 sentences), front-loaded with the main action, and every sentence serves a purpose: stating the function, listing source types, explaining validation, and linking to sibling tools. No wasted words or redundancy.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description provides sufficient context: it explains the output types, validation process, and that existing sources are excluded (via parameter description). It lacks a detailed proposal format, but the coverage is adequate for an agent to understand the tool's behavior and integrate with siblings.

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 clear descriptions for both parameters. The tool description aligns with the 'description' parameter but does not add significant new semantics beyond what the schema provides. Baseline 3 is appropriate given the 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: 'Describe a subject in plain words and get back real, working sources for it.' It lists the types of sources (RSS feeds, web searches, newsletters) and explicitly distinguishes from siblings by noting that it returns proposals to pass to add_feed / add_web_search, making the verb-resource pairing specific and unambiguous.

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

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

The description provides clear context by stating that the tool returns proposals to pass to add_feed / add_web_search, implying it is for discovery, not addition. It also notes 'Nothing is added' to reinforce its read-only nature. However, it does not explicitly state when not to use it or compare with other discovery tools (none exist), preventing a perfect 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?

The description discloses key behavioral traits beyond annotations: it costs real AI money, takes a couple of minutes, and returns an ID for polling. Annotations provide no readOnly, idempotent, or destructive hints, so the description carries the full burden and does so effectively.

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

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

Three sentences, each serving a distinct purpose: action, usage guidance, and return value. Front-loaded with the primary action. No redundant or extraneous information.

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

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

Given no parameters, no output schema, and an existing sibling for polling (get_briefing), the description is largely complete. It covers what the tool does, when to use it, and what to do with the result. Could mention potential failure modes or idempotency, but not required for this simple tool.

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

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

The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description adds value by explaining that the briefing uses 'everything collected so far', which clarifies the implicit input context.

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

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

The description clearly states the action (generate a briefing immediately), the resource (briefing), and the context (using everything collected so far, instead of waiting for scheduled time). It distinguishes itself from the scheduled workflow and implicitly from sibling tools like get_briefing (polling) and correct_briefing (editing).

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 'use it only when explicitly asked' due to cost and time, providing clear when-to-use guidance. It implies the alternative is waiting for the scheduled time, but does not name specific sibling tools as alternatives or 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 provides a comprehensive list of the data fields returned (plan, briefing running, next due date, source/story counts, AI cost), which is behavioral transparency beyond the readOnlyHint annotation. The annotation already indicates a safe read operation, and the description adds value by detailing what is fetched. 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 sentence that lists all relevant data fields with commas and a conjunction. Every word adds value, and there is no redundancy or verbosity.

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 parameters, no output schema, and a simple read operation, the description is complete enough. It lists all likely return fields, and the sibling tools cover other capabilities. The only minor gap is that it does not mention the return format (e.g., JSON structure), but for a zero-param tool, this is acceptable.

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

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

The input schema has no parameters, so the description does not need to add parameter meaning. The schema coverage is 100%, and the description compensates by explaining the output, which is the only relevant semantic aspect. A baseline of 4 is appropriate for a zero-parameter tool.

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

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

The description clearly states that the tool returns account status, including plan, briefing status, next due date, source and story counts, and AI cost. This is a specific verb-resource pairing ('get account') with a detailed breakdown of what is returned, distinguishing it from sibling tools that manage feeds, briefings, or sources.

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 the tool is used to check account-level information, and the sibling tools list includes many alternatives for specific actions (e.g., add_feed, generate_briefing), so the context helps differentiate. However, there is no explicit guidance on when to use this tool versus alternatives, nor any 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 annotations already indicate readOnlyHint=true (read-only) and no destructive hint. The description adds clarity that the tool returns full markdown and an index, and offers defaults. It does not contradict annotations and provides useful extra behavior context 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?

Three sentences cover purpose, scope, and additional use case (index for rating/correction) without any filler. Information is front-loaded and every sentence is necessary.

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

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

Given the tool's simplicity (2 optional params, no output schema, low complexity), the description is complete. It explains what the tool returns, how to get different briefings, and links to entry IDs for sibling tools. No missing details for an agent to use it correctly.

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

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

The input schema has 100% description coverage for both parameters. The description adds context that 'briefing_id' relates to listing from 'list_briefings' and that omitting it gets the latest, and 'include_markdown' controls text vs index. This adds value beyond the schema alone.

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

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

The description clearly states the tool reads a personal AI-written news briefing in full markdown. It specifies the content (newsletters, RSS feeds, web searches) and the options to retrieve by id or date, with an index of entry ids for further actions.

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 this tool (to read a briefing) and notes the index is needed for rating or correcting stories, which hints at using sibling tools like 'rate_briefing_entry' and 'correct_briefing'. However, it does not explicitly contrast with siblings like 'generate_briefing' or 'list_briefings'.

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 the description confirms via 'Read everything'. The description adds value by detailing the returned content (topics, preferences, learned profile, etc.), which is not in the annotations. However, it does not describe the return format or structure (e.g., whether it's a flat object or nested), and no output schema exists. The description is transparent but slightly incomplete for a read operation with no output schema.

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

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

The description is two sentences: the first sentence lists the major components in a clear, comma-separated manner; the second sentence reinforces the purpose with an imperative. Every word adds value, and the key action ('read') is front-loaded. No fluff.

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

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

Given the tool has no output schema, the description must convey the return value. It lists a comprehensive set of data points (schedule, length, technicality, depth, stance, tone, interests, no-go topics, learned profile, per-topic preferences). However, it does not specify the structure (e.g., whether it's a single object or a list of items) or provide any examples. The sibling set is large, but the description sufficiently distinguishes this as the full read. Slightly incomplete for a tool with such a broad return scope.

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?

There are no parameters (0 params, 100% schema coverage). The description correctly adds no parameter-specific information because none are needed. Baseline for zero-parameter tools is 4, and the description does not detract from that.

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

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

The description clearly states the verb 'Read' and the resource 'everything that shapes what reaches this person', listing multiple specific components (delivery schedule, length, technicality, etc.). It distinguishes from sibling tools like 'update_information_diet' (write counterpart) and other read tools (get_account, get_briefing) by emphasizing it provides the full picture of the news filter.

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 'read it before changing anything', signaling the tool should be used as a prerequisite to mutation tools like 'update_information_diet'. While it doesn't enumerate alternatives or when not to use, the context and sibling names imply the specialized read tools (e.g., get_account, get_briefing) cover sub-parts. The guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, so safety is known. The description adds meaningful behavioral context: it returns a private podcast narrated in the user's language, with a playable URL and show notes listing sources, and defaults to the latest episode. This goes beyond the read-only hint and sets accurate return expectations.

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, tightly written sentence that leads with the main action and includes essential output details. It is front-loaded with 'Get the audio episode' and contains no redundant or vague phrasing, making it highly efficient.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description sufficiently covers what an agent needs: what the tool does, what it returns, and the default behavior. It does not introduce unnecessary complexity and leaves no obvious gaps.

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

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

The single parameter briefing_id is fully described in the schema ('Episode of a specific briefing. Omit for the latest.'), and the description repeats the default-latest behavior. Since schema coverage is 100%, the description adds no new semantic value, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool gets the audio episode generated from a briefing, with a specific verb and resource. It details the output (playable URL, show notes, language) and differentiates from sibling tools like get_briefing by focusing on the audio format.

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 the tool: to retrieve the podcast version of a briefing, with the optional briefing_id for specific episodes. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to understand this is the audio-episode counterpart to other briefing tools.

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

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

Annotations already provide readOnlyHint=true, but the description adds rich behavioral context: what is inspected (RSS feeds with health and last fetch, web searches, X/Twitter profiles, newsletters). It also reinforces the read-only nature by describing inspection rather than mutation. 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 two sentences with no wasted words. The first sentence front-loads the purpose and details; the second provides actionable usage advice. Every sentence adds value.

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

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

For a simple read-only inspection tool with no output schema, the description adequately lists the return components. It does not describe the response structure in detail, but that is not strictly necessary for decision-making. The annotation and schema cover remaining context.

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

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

Schema coverage is 100% (one parameter fully described as 'Id from list_sources'). The description does not add additional meaning beyond the schema, such as format or validation rules. Per guidelines, high coverage yields baseline 3.

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

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

The description clearly states the tool inspects one topic inbox in detail, listing specific components (RSS feeds, web searches, profiles, newsletters). It distinguishes from sibling tools like delete_source and update_source by focusing on inspection. The verb 'inspect' and resource 'topic inbox' are specific and differentiated.

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

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

The description explicitly says 'Use it before removing or reorganising anything,' providing clear when-to-use guidance. It implies the tool is not for modification, but does not explicitly name alternative tools like delete_source or update_source. This is clear context without full 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds critical behavioral context: the batch process validates feeds one by one and returns failures with reasons. It also reveals the dry-run pattern, which is vital for agent decision-making. Without annotations, this would be a 5, but the annotation burden reduces the score slightly.

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 wasted words. The first sentence states the what and who (supported sources). The second covers the workflow and edge cases. Every sentence serves a distinct 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 tells the agent what to expect (failures with reasons) and how to use the tool correctly (dry-run first, batch processing). The sibling list shows many tools for feed management, and this description equips the agent to choose this for bulk OPML imports without confusion.

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%, meaning all 4 parameters have schema descriptions. The tool description adds value beyond the schema by explaining the workflow (dry_run usage) and the consequence of the limit parameter ('big imports go in batches'). This surpasses the baseline 3 for high coverage.

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

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

The description uses specific verbs ('Import subscriptions') and identifies the exact resources (OPML file) and common sources (Feedly, Inoreader, etc.). It clearly distinguishes from siblings like add_feed (single feed) and add_web_search, making the tool's 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 explicit guidance on the workflow: first set dry_run true to preview, then run for real. It also mentions validation behavior and error reporting. However, it doesn't explicitly contrast with siblings like create_source or discover_sources, leaving some ambiguity about when to use this vs. alternative bulk operations.

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

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

Annotations already declare readOnlyHint=true, so the description confirms this is a safe read operation. The description adds useful behavioral detail: ordering (most recent first), returned fields (date, title, number of stories, episode existence), and intended follow-up usage (read or correct). No annotation contradiction exists.

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, both earn their place: the first lists what is returned and ordering; the second explains the use case. It could be slightly more concise by merging, but is effective and well-structured.

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

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

Given the tool has only one optional parameter, no output schema, and existing annotations, the description provides enough information for an agent to use it effectively. It explains the purpose, what fields are returned, and the use case. Missing details like whether the list is paginated or the exact date format are minor gaps but acceptable for a simple 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%, so the schema already documents limit with min, max, and default. The description adds no extra parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists past daily briefings, orders them most recent first, and specifies the fields returned: date, title, number of stories, and whether an episode exists. It distinguishes from siblings like get_briefing (which gets a specific one) by mentioning finding the id before reading or correcting.

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

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

The description explicitly states the tool should be used to find the id of a specific day before reading or correcting it, providing clear context. However, it does not mention when NOT to use it versus siblings like list_deep_dives or list_read_later, which could be used for other list needs.

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 openWorldHint=false. The description adds value by clarifying these are 'requests waiting to be covered' and that they involve 'fresh web research', but does not disclose additional behavioral traits like ordering, pagination, or potential staleness of the list.

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 sentence clearly stating what the tool lists and providing context about what deep dives are. Every word adds value with no redundancy.

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

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

For a parameterless read-only list tool with no output schema and clear annotation support, the description sufficiently explains the purpose and context of the returned items. It does not describe the output format, but given the simplicity and the fact that the tool name implies a list, this is a minor gap.

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 no parameters and schema description coverage is 100%, so there is no parameter information to supplement. The description does not need to add parameter meaning; the baseline is high and the tool is trivially parameterless.

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 lists 'deep-dive research requests waiting to be covered', specifying both the resource type and status. However, it does not distinguish this from other list tools among siblings like list_briefings, list_sources, or list_read_later, which are distinct enough that confusion is unlikely.

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 this tool is used to see what topics are pending investigation, which provides contextual usage guidance. However, it offers no explicit direction on when to use this over alternatives (e.g., request_deep_dive, generate_briefing) 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?

The annotations already declare `readOnlyHint: true` and `openWorldHint: false`. The description adds value by revealing a behavioral trait beyond the annotations: the listed items are 'guaranteed to be covered in the next briefing,' which is a temporal constraint not inferable from annotations alone.

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

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

The description is a single, front-loaded sentence that conveys purpose and a key constraint without any wasted words. Every element 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 tool has no parameters, no output schema, and the annotations provide basic hints, the description covers the essential purpose and a key behavioral guarantee. It lacks details about the return format (e.g., does it return titles, dates?), but with no output schema, that is a minor gap for such a simple 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?

The tool has zero parameters and the schema description coverage is 100% (no schema details to cover). The description does not need to add parameter meaning since there are none. A baseline of 4 is appropriate as the description cannot add more value here.

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 lists the read-later queue, specifying the contents as 'links and forwarded emails' and a key distinguishing constraint: 'guaranteed to be covered in the next briefing.' This is specific and distinguishes it from siblings like `list_briefings` or `save_for_later`.

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 this tool: to preview items that will appear in the next briefing. It does not explicitly state when not to use it or name alternatives for viewing items not in that queue, but the guarantee of coverage provides clear context for its specific use case.

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, so the description reinforces a read operation. It adds behavioral context beyond annotations by specifying exactly what data is returned (email address, RSS, web searches, production stats, priority, inclusion). No side effects or authorization details are mentioned, but the description aligns with the annotations and complements them well.

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 the core purpose, and every word contributes value. No redundancy or unnecessary detail. 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 no output schema and low complexity (0 parameters), the description adequately covers what the tool returns: each source's email, RSS, web searches, recent production, priority, and inclusion status. It could be slightly more explicit about scope (e.g., 'the current user's topic inboxes'), but overall it is sufficiently complete 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?

The input schema has no parameters and schema coverage is 100%. With 0 parameters, the baseline is 4. The description does not need to explain parameters, and it adds no parameter-related meaning beyond the schema, which 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 lists 'topic inboxes' (information sources) for a person's briefing, detailing what each includes (email address, RSS feeds, web searches) and what performance metrics are shown (recent production, priority, inclusion). The verb 'list' and resource 'information sources' are specific, and the description distinguishes this from siblings like list_briefings, list_deep_dives, and list_read_later.

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 context—when needing to view available sources for a briefing—but does not explicitly state when to use this tool versus alternatives like discover_sources or get_source. No exclusion criteria or conditions are mentioned. While the purpose is clear, explicit guidance on when not to use it would improve selection accuracy.

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?

It discloses non-obvious stateful behavior beyond the sparse annotations: signals apply to topics, future briefings weigh them differently, re-sending with different topics replaces the previous signal, dropped topics are restored, and nothing is double-counted. This is especially valuable for a mutating tool with no idempotence guarantee.

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 dense sentences with no filler. The main action and examples come first, while the replacement edge case is saved for last. Every sentence contributes distinct, necessary 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?

For a mutation tool with no output schema, the description covers the target entry, optional briefing, topic scoping, and side effects on future briefings. An agent has enough to call it correctly and predict the outcome.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning the schema cannot convey: that a story usually has several topics, that `topics` can narrow the signal to a subset, and that repeating the call with different topics replaces the old signal rather than accumulating.

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

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

The description opens with a precise verb and resource: 'Give a precise up/down signal on one story of a briefing.' It enumerates the possible signals and scopes the effect to the story's topics, which clearly distinguishes it from broader preference tools like tune_topic.

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 the tool is for adjusting future briefings based on a specific story and explains how to restrict to certain topics. However, it does not explicitly say when to prefer it over overlapping sibling tools such as tune_topic or set_learned_profile, nor does it give 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 indicate destructiveHint=true and idempotentHint=true. The description adds value by explaining the exact behavioral effect: 'Already-collected content stays; nothing new arrives from it.' This goes beyond the annotations in detailing what is preserved and what changes.

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 extremely concise sentences. The first sentence states the primary purpose clearly, and the second adds essential nuance. No wasted words. The structure is 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 low complexity (one required parameter, no output schema, simple behavior), the description covers all necessary aspects: what the tool does, its effect on existing vs. new content, and the required input. 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?

The single parameter feed_id has 100% schema coverage with a description referencing get_source. The description does not add any extra details about the parameter, so it does not improve upon the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Remove an RSS feed from a topic inbox') and adds the nuance that already-collected content stays while new content stops. This distinguishes it from similar operations like delete_source which might remove everything.

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 clearly implies when to use the tool: to stop new content from a specific feed without losing existing content. However, it does not explicitly state when not to use it or mention alternatives like delete_source for complete removal, which would make it even clearer.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds valuable context: it clarifies that no new results will arrive and that previously collected data persists. This explains the nature of the 'destructive' behavior and matches the idempotency hint.

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 short sentences—with the primary action front-loaded. Every word adds value; there is no redundancy or filler.

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

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

Given the tool's simplicity (one parameter, no output schema), the description adequately covers what happens when the tool is invoked: it stops monitoring without deleting collected data. It is sufficient for an agent to understand the outcome.

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 'search_id' described in the schema. The tool description does not add further parameter details, so it meets the baseline but does not exceed it.

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

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

The description clearly states the verb 'Stop monitoring' and the resource 'standing web search', distinguishing it from siblings like 'remove_feed' or 'add_web_search'. It is specific and unambiguous.

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

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

The description indicates when to use this tool (to stop monitoring a search) and implies the effect (no new results, existing data remains). It does not explicitly mention alternatives or when not to use it, but the context is clear enough for an AI agent.

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 well beyond the annotations by disclosing concrete side effects: the editor investigates sources and preferences, may follow topics, and may queue a deep-dive for the next briefing. It also mentions the five-per-day limit. These details meaningfully inform an agent about the tool's non-readonly behavior, complementing the readOnlyHint=false 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 dense but not bloated; every clause contributes useful information about what happens when the tool is invoked. The verdict categories and side effects are front-loaded enough, though the long middle sentence could be split for easier scanning.

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

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

For a tool with only two parameters and no output schema, the description covers the trigger, the input semantics, the possible verdicts, the side effects, and the rate limit. An agent has enough context to invoke it appropriately and to interpret the likely result.

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

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

Schema description coverage is 100%, so the schema already documents both text and briefing_id. The description adds little beyond reinforcing that the story should be described 'in their words'. This meets the baseline but does not exceed it.

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

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

The description clearly states the tool's purpose: a reader reports a story they expected, and the editor investigates and returns a verdict about why it was missing. It enumerates the possible verdicts and side effects, which distinguishes it from sibling tools like request_deep_dive or correct_briefing.

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 opening sentence gives the exact trigger condition: the reader expected a story and the briefing did not have it. This tells the agent when to use the tool, though it does not explicitly contrast it with alternatives such as correct_briefing or request_deep_dive. Still, the context is clear enough to avoid major misuse.

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 idempotentHint=true, readOnlyHint=false, destructiveHint=false, giving a basic safety profile. The description adds behavioral context: the tool will produce 'a mini-dossier with sources' via 'fresh web research', which is not captured in annotations. It does not contradict annotations and provides useful additional detail. No discussion of rate limits or auth needs, but the tool is simple enough that this is acceptable.

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, each earning its place. The first sentence states what the tool does and its output. The second sentence gives concrete usage scenarios. No filler or redundant information. 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 tool's simplicity (one parameter, no output schema, annotations present), the description covers purpose, usage scenario, and output format. It is sufficiently complete for an agent to select and invoke the tool correctly. It could be slightly more explicit about the queuing nature (e.g., 'for the next briefing'), but it is implied. Score 4 reflects good completeness for a simple tool.

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

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

The input schema has 100% coverage for the single 'query' parameter with a description: 'The question or topic to research'. The tool description adds that the query will be used for 'fresh web research' and to produce a mini-dossier, but this is about the tool's overall behavior, not additional parameter constraints or formatting. Since the schema already documents the parameter fully, 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's purpose: 'Ask the next briefing to investigate a topic properly, with fresh web research: it will include a mini-dossier with sources.' This makes it immediately obvious that the tool queues a research task for a briefing. It distinguishes itself from siblings like 'list_deep_dives' (which lists results) and 'generate_briefing' (which generates a full briefing) by focusing on the deep-dive request mechanism.

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

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

The description provides explicit usage guidance: 'Use it whenever the person says

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 valuable behavioral context beyond annotations: 'The page is fetched and its text stored, so it can be summarised even if the site later blocks access.' This discloses a non-obvious behavior and benefit. Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true) 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 two sentences, front-loaded with the primary action and outcome. The second sentence explains a key behavioral detail without unnecessary elaboration. Every sentence contributes to understanding.

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

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

For a 3-parameter tool with no output schema, the description provides sufficient context: purpose, input types, and what happens to the saved item. Minor gaps exist, such as not clarifying whether url and text are mutually exclusive or if at least one is required, but annotations and schema partially compensate.

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

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

Schema descriptions cover 100% of parameters, so the baseline is 3. The description adds little beyond the schema: it restates the two modes (url or text) but does not add format, constraints, or interaction details. The optional title is already described 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 action ('Put a link or a note into the read-later queue') and the resource/outcome ('whatever lands there is guaranteed to be covered in the next briefing'). It differentiates from sibling tools like add_feed and create_source by focusing on a one-off read-later queue rather than persistent sources.

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 context (items to be covered in the next briefing) but does not explicitly state when not to use this tool or name alternatives. Sibling tools suggest related but distinct use cases, yet the description relies on the agent to infer the distinction.

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 destructiveHint=true and readOnlyHint=false, and the description aligns by saying 'rewrite' and 'append'. It adds valuable context that replacing destroys existing profile content while appending preserves it, which goes beyond the annotation's bare destructive flag. No contradiction found.

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 the core purpose, followed by actionable guidance. No redundant filler; every clause earns its place. The structure is clean 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?

The description covers the tool's purpose, profile content, and mode semantics, which is sufficient for a simple setter with no output schema. However, the odd 'read or rewrite' phrasing could confuse an agent about whether a read-only retrieval is possible, creating a minor completeness gap.

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 parameters. The description enhances this by explaining how 'text' behaves depending on mode ('add a line' for append vs. implied full replacement) and reinforces the default append behavior, adding meaning beyond the schema's enum and field 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 identifies the resource (the learned profile) and actions ('read or rewrite'), but the dual verb 'read or rewrite' is ambiguous; the tool name and schema indicate it is primarily a write operation. It distinguishes from siblings by clarifying the profile's role in briefings, but the ambiguity mildly weakens purpose clarity.

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 guidance on mode selection ('Appending is usually better than replacing: pass mode "append" to add a line'), but does not explicitly state when to use this tool versus alternatives like correct_briefing or tune_topic. Usage context is implied by describing the profile's purpose, but no exclusions are given.

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

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

Despite minimal annotations (no readOnly, no destructive hints), the description enumerates all possible actions (more, less, mute, follow, etc.) and clearly states the effect is on 'future briefings'. It does not describe side effects like irreversibility of mute, but the action list itself provides transparency. 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 total: the first states the tool's purpose and lists possible actions, the second provides usage guidance. No redundant or filler content. Every sentence serves a clear function.

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 two parameters, no output schema, and moderate complexity, the description covers what the tool does and when to use it. It does not explain what the return value looks like (e.g., confirmation or error), but the absence of an output schema lowers the expectation. The description is adequate for correct agent selection and invocation.

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

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

Schema coverage is 100% (both parameters documented). The description adds value beyond the schema by specifying that 'topic' should be 'as it appears in get_information_diet or in a briefing entry' and by listing the action categories in prose (e.g., 'more or less of it, more or less technical'), which gives context to the enum values.

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

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

The description clearly states the verb 'tune' and the resource 'a single topic' with the specific purpose of adjusting how it is treated in future briefings. It distinguishes itself from the sibling tool 'correct_briefing' by contrasting 'precise instrument' vs 'vague comment', making the tool's unique role obvious.

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

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

Explicit guidance is provided: 'for a vague comment like "too much crypto lately" use correct_briefing instead'. This tells the agent exactly when to use this tool versus an alternative, and the opening sentence implies it is for precise, granular adjustments.

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 set destructiveHint=true and readOnlyHint=false, indicating mutation. The description adds significant value by disclosing that the tool may either perform the unsubscribe directly or return a URL that requires human intervention. This goes beyond annotations and sets accurate expectations 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 two sentences long with no wasted words. Every sentence adds essential behavioral context, including the conditional behavior of the server-side vs. human-intervention pathway.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all critical aspects: purpose, behavior, and two possible outcomes. It slightly lacks explicit mention of return format (e.g., does it return a string URL?) but is otherwise complete for a straightforward operation.

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

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

Schema coverage is 100%, so the single parameter is already documented in the schema. The description does not add any additional meaning or usage details for the newsletter_id parameter beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Unsubscribe' and resource 'newsletter', clearly distinguishing it from sibling tools like 'delete_source' or 'add_feed'. It also clarifies the domain ('arriving in one of the inboxes'), making the tool's intent unambiguous.

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

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

The description provides clear context on when to use it (to unsubscribe), and transparently explains two behavioral scenarios: direct server-side unsubscribe vs. returning a URL for manual action. It does not, however, explicitly contrast with alternatives like 'delete_source' or suggest 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 idempotency and non-destructiveness, so the description does not need to restate those. The description adds valuable behavioral context beyond annotations by clarifying that the updates are global settings, that only provided keys are changed, and that it mutates settings rather than creating or deleting anything. This is consistent with readOnlyHint=false and 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?

Three sentences with no waste: the first sentence front-loads the tool's full scope, the second gives the partial-update rule, and the third orients the agent with a prerequisite and a sibling alternative. 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 a complex 20-parameter mutation tool with no output schema, the description is largely complete: it orients the agent to read the current settings first, limits scope to global settings, points to tune_topic for per-topic changes, and lists the affected dimensions. It does not describe return values, but none are expected for an update, and annotations cover safety/repeatability. A small gap is that it does not mention whether a confirmation or error is returned, but this is minor.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not explain individual parameter formats or meanings, and its "Pass only the keys you want to change" mirrors the schema's "Any subset of the settings". It adds the useful global-vs-per-topic framing but does not add new per-parameter semantics 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 states a specific verb and resource: "Change how and when the briefing reaches this person" and enumerates the many settings it covers. It distinguishes itself from the sibling tune_topic by explicitly saying these are global settings, not per-topic ones. An agent can immediately tell what this tool does and what it is not for.

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 guidance: "Read get_information_diet first", "these are global settings, not per-topic ones", and "for a single topic use tune_topic". It also instructs partial updates with "Pass only the keys you want to change", leaving no ambiguity about 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 adds behavioral meaning beyond the annotations by distinguishing 'temporarily exclude from the briefing' from 'pause it entirely', which maps to include_in_digest versus is_active. Annotations already cover idempotence and non-destructiveness, and the description does not contradict them.

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

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

A single, front-loaded sentence lists all update capabilities with zero wasted words. Each clause contributes a distinct operation, making the description both compact and informative.

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

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

The description covers all seven parameters' intent and works with the annotations to convey a safe, idempotent update operation. It could explicitly state that unspecified fields are left unchanged (partial update), but this is inferable from the schema's required list and is a minor gap.

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 each parameter already carries a meaningful description. The tool description adds a helpful operation-to-parameter mapping, but no new syntax or facts beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb ('Change') and resource ('a topic inbox') and enumerates the concrete updates: rename, edit description, adjust priority, set technicality, exclude from briefing, or pause. This clearly separates it from create_source, delete_source, and get_source.

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 specifies exactly which operations call for this tool (renaming, changing description, priority, technicality, briefing exclusion, pausing), giving an agent clear scenarios to use it. It does not explicitly name alternatives or exclusions like create_source/delete_source, so it falls short of a 5.

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