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?

Annotations already declare the mutation/idempotent/openWorld safety profile, so the bar is lower. The description nonetheless adds real value: the idempotency outcome ('adding twice says it was already added') and the destination ('the inbox it indicated'). It does not cover auth/permission needs, which is a minor gap given annotation coverage.

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 short sentences, front-loaded with the originating condition before the action. 'the same tap the reader has under the briefing' is slightly colloquial but contextual, not filler. Nothing is redundant enough to cut.

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

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

For a single-parameter mutation tool with annotations and no output schema, the description covers purpose, trigger, destination, and idempotency. Missing only edge behavior on failure, which is minor given the annotation coverage.

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 single report_id parameter is fully documented in the schema as the investigation id. The description adds no format or sourcing detail beyond that; the baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: it adds a proposed feed that report_missing_story generated, routing it into the indicated inbox. It names the originating sibling (report_missing_story), which anchors the purpose well. It stops short of explicitly differentiating itself from add_feed/create_source, but the origin story makes the role clear.

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

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

Usage is implied through the scenario: use this after report_missing_story has proposed a source. There is no explicit when-not or direct routing advice against the closely related add_feed or create_source siblings. An agent can infer the trigger but is left to reason about alternatives itself.

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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a real failure-mode gate not present in annotations: only queued requests are cancellable, and already-briefed ones are not.

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 short sentences, front-loaded with the action and its scope, then the exclusion. Nothing is redundant and no sentence is filler.

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

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

For a one-parameter mutation with no output schema, the description covers purpose, precondition, and id provenance, with annotations handling safety. It does not say what happens on an invalid/already-covered id (silent no-op vs. error), which is a minor remaining 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?

Single parameter with 100% schema description coverage, so the schema already documents it. The description's 'ids from list_deep_dives' repeats what the schema property description already says, adding no new syntax or format detail beyond the baseline.

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

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

Uses a specific verb (remove) plus the resource (a queued deep-dive request) and states the operational scope ('still waiting'). It is clearly distinct from request_deep_dive, though it does not explicitly name that sibling or contrast with the other list_* 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?

Gives both the when ('a request that is still waiting') and an explicit when-not ('One already covered in a briefing cannot be cancelled'), which is exactly the precondition an agent needs before invoking. The id source (list_deep_dives) is also named.

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=false, idempotentHint=false and destructiveHint=false, so the write/non-idempotent nature is already signaled. The description adds real context beyond that: an AI editor interprets the free-text note against the actual briefing and converts it into topic preferences, settings, and deep-dive requests, which tells the agent the note is not a literal command but a interpreted input.

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

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

Front-loaded with the core verb and illustrative examples that earn their place, and the entry_id caveat is a genuinely useful routing detail. The final sentence is somewhat tangled, stacking the pin-one-story path and the rate_briefing_entry alternative, which slightly dilutes readability.

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

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

No output schema exists, and the description compensates by explaining what the AI editor produces (topic preferences, settings, deep-dive requests) and the entry_id/briefing_id scoping rules. Adequate for the agent to call it correctly; minor gaps remain about validation or failure behavior of an ambiguous note.

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 baseline is 3, but the description adds genuine semantics: entry_id scopes the note to one story for follow behavior, the absence of entry_id limits it to a whole theme, and briefing_id defaults to the latest. That is meaning beyond the schema's own field text.

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+resource ('correct the briefing') and immediately grounds it with concrete example notes, so the effect on the news feed is unambiguous. It also distinguishes itself from siblings by naming rate_briefing_entry and describing the entry_id path for following a single story.

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 frames this as 'the main way a person retunes their news feed by talking', then gives the alternative route: pass entry_id to pin one story, or use rate_briefing_entry with follow. It even spells out the boundary condition that a note without entry_id can only follow a whole theme.

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?

Annotations only declare the generic safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds genuinely non-obvious behavior: it is long-running ('takes a few minutes') and therefore requires polling, it has a side effect beyond generation ('it also lifts the automatic pause'), and it incurs real monetary cost. These are exactly the traits annotations cannot express.

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 short sentences, front-loaded with the action and its default, then duration, then the cost/side-effect caveat. Every clause carries distinct information 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 an async, cost-incurring mutation with no output schema and one optional param, the description supplies everything an agent needs: how long it takes, how to retrieve the result, the hidden side effect on the pause state, and the cost constraint.

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 single parameter's description ('Omit for the latest') already documents the optional semantics; the description's 'the latest by default' largely restates it. One optional parameter also places this at the default 4 baseline conceptually, but since the description adds no format or ID-syntax guidance beyond the schema, a 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 and resource ('Make (or remake) the podcast episode of a briefing') plus the default scope ('the latest by default'). It is clearly distinguishable from the read-side sibling get_podcast_episode, which the description explicitly names as the polling counterpart.

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

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

Gives explicit when ('only when asked'), when-not (implied by the cost warning, 'costs real AI money'), and the alternative workflow ('poll with get_podcast_episode'). Nothing about selection is left to inference.

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?

readOnlyHint already covers the safety profile, but the description adds real behavioral context beyond the annotations: the two transcript formats ('Name: line' turns vs. plain paragraphs) and the default-to-latest behavior. It omits length/pagination expectations, keeping it from a 5.

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

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

Front-loaded with the core identity, then format, then usage triggers, then the default. Every sentence carries content, though the format sentence is somewhat detailed for a short tool description.

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

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

No output schema exists, but the description compensates by describing the returned text's structure. With both params fully documented and the read-only profile covered by annotations, an agent has what it needs to call this correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including 'Omit for the latest' for briefing_id. The description's 'Latest episode by default' restates that default rather than adding new meaning, 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 a specific verb-resource pairing: 'The full text of a podcast episode, word for word: the script the voices read.' It also alludes to the contrast with the written briefing, which helps separate it from get_briefing/get_podcast_episode, though it never names a sibling tool outright.

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?

Gives explicit when-to-use triggers: quoting a passage, retrieving a point the briefing lacks, or searching spoken content. No when-not conditions or named alternatives are provided, so it stops 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description doesn't need to restate it. The description adds genuine behavioral context by spelling out the scope of data returned (schedule, format, learned profile, per-topic preferences, pinned stories), which goes beyond what the annotations convey.

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

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

The main verb and resource are front-loaded, which is good, but the enumeration of data fields runs on as a single ~80-word sentence that is list-heavy and hard to scan. Every element is arguably informative, yet the structure is dense rather than tight.

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

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

There is no output schema, so the description carries the burden of telling the agent what comes back, and it does so thoroughly by enumerating the config dimensions. A brief note on the response shape or size would make it fully complete.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing further the description could meaningfully add on parameter semantics.

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 ('Read') plus the precise resource (the information diet, i.e. the full personalization/news-filter config), then enumerates the exact fields it covers. Combined with the closing 'read it before changing anything', an agent can distinguish this from update_information_diet without opening either schema.

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 'read it before changing anything' implies this is a prerequisite read before mutations, which is useful implied ordering. However, it never names update_information_diet or other siblings as the alternative, nor states exclusions, so the guidance stays at the implied level.

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, so safety is covered; the description goes further by disclosing what is actually returned (playable URL, private RSS feed URL, show notes listing every source) and the default-latest behavior. The 'private' framing hints at access scoping, though it does not spell out any auth or ownership requirement.

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

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

Front-loaded with the verb and resource, then builds scope, format options, return values and the sibling escape hatch in three efficiently packed sentences. Nothing repeats the title or wastes space.

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

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

With no output schema, the description correctly compensates by enumerating the return payload (audio URL, RSS feed URL, show notes with sources) and the default resolution rule. Combined with annotations covering the read-only profile, an agent has enough to call it correctly; only failure/empty states are unaddressed.

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 single parameter already documents 'Episode of a specific briefing. Omit for the latest.' The description only restates the default-latest behavior, adding no syntax, format or ID-shape detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Get the audio episode generated from a briefing') and immediately narrows the resource further: a private podcast in two formats with a playable URL, RSS feed and show notes. It explicitly names the sibling that covers the adjacent-but-different need ('For the words themselves use get_episode_transcript'), so the agent can separate it from get_episode_transcript and generate_podcast_episode without opening any schema.

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?

Gives a clear routing rule to the alternative tool for transcripts and states the default selection behavior ('Returns the latest episode by default'). It does not say what to do when no episode exists yet (i.e. that generate_podcast_episode is the creation path), which is the one obvious exclusion left unstated.

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 and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the ordering guarantee (most recent first) and the exact shape of each listed item, including whether an episode 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?

Two tight sentences with zero waste; purpose and ordering come first, then the concrete usage guidance. Every clause 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 read-only list tool with no output schema, the description compensates by enumerating the returned fields and ordering, and the schema fully documents both pagination parameters. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so limit and offset are fully documented in the schema, including the archive-walking purpose of offset. The description adds no parameter detail, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (the user's past daily briefings), specifies ordering (most recent first) and the fields returned (date, title, story count, episode existence). An agent can distinguish this listing tool from get_briefing, list_deep_dives, or list_missing_reports without opening the schema.

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 the use case: find the id of a specific day before reading or correcting it, which routes the agent toward get_briefing/correct_briefing. Clear context, but it does not name those siblings by tool name or state when-not-to-use, 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.

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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context by detailing what each investigation record contains (what was asked, verdict, explanation, signals applied, proposed source and whether it was added), which annotations cannot convey. It omits ordering/pagination, hence not a 5.

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?

It is a single, front-loaded sentence that names the resource first, then qualifies it. The em-dash clause is dense but informative rather than redundant. Slightly heavy for one parameter, but no 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?

With no output schema, the description usefully enumerates the returned fields, which is the main completeness burden here. Combined with full schema coverage and read-only annotations, an agent has what it needs; only ordering/pagination behavior is unspecified.

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 there is a single optional parameter, so baseline is 3. 'Latest briefing by default' merely restates the schema's 'Omit for the latest' rather than adding format or scoping detail.

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 precisely as the investigations opened via report_missing_story on a briefing, and enumerates their contents, which cleanly separates it from get_briefing and list_briefings. It never states the verb 'list/return' directly, relying on the name, but the resource is unambiguous.

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

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

The only usage signal is 'Latest briefing by default' and the implicit link to report_missing_story, which implies this is where you revisit investigations already opened. There is no explicit when-to-use vs. report_missing_story or list_briefings, and no exclusions, so guidance is implied rather than stated.

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, so the safety profile is covered. The description adds genuinely useful semantics beyond that: it distinguishes items guaranteed to appear in the next briefing from snoozed items that wait until their date, which tells the agent how to interpret the output.

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

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

A single front-loaded sentence that leads with the core action and then qualifies the contents. The nested parenthetical and em-dash make it slightly dense, but every clause carries information and nothing is wasted.

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

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

With no parameters and no output schema, the description's main job is to characterize what comes back, and it does so by naming the three item classes. The one remaining gap is the absence of any tie-break against the sibling list_saved.

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 takes zero parameters and the schema is trivially complete (additionalProperties=false), so there is nothing for the description to clarify. Baseline 4 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 a specific verb (list) and resource (read-later inbox) and even enumerates the categories of items it returns (links, forwarded emails, snoozed stories). It does not, however, name or contrast against the closely related sibling list_saved, leaving the agent to infer the boundary between the two queues.

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?

Usage is only implied: the description says what is queued but never states when to call this versus list_saved, list_briefings or save_for_later, nor does it give any precondition. Nothing is misleading, but the agent gets no routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely new context: newest-first ordering, that entries carry their originating briefing, and the inclusion of the 'chicca' archive story. It stops short of describing pagination or result volume.

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 tight sentences, front-loaded with the resource definition and ending with the routing hint. The 'chicca' parenthetical is mildly jargon-heavy but serves a genuine documentation 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 read-only list tool with annotations covering the safety profile, the description supplies sort order, result composition, search scope, and routing to the write siblings. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by enumerating what `query` searches across (title, text, topics, briefing title) rather than leaving it as 'a word to search for'. The `limit` parameter is left to 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?

States a specific resource and scope: saved stories from briefings, including the 'chicca' archive item, with newest-first ordering. It also names the write siblings (save_entry, unsave_entry). It does not, however, distinguish itself from the similarly-named list_read_later sibling, which an agent must resolve on its own.

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 routes mutation intent to save_entry/unsave_entry and explains the `query` use case, giving clear context for calling this tool. No when-not guidance and no disambiguation against list_read_later 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 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?

Annotations already declare a non-read-only, non-idempotent, non-destructive mutation; the description goes beyond them by disclosing replacement semantics, that withdraw restores the touched topics, and that follow pins only this story. It omits auth requirements and any error/conflict behavior, so it is strong but not exhaustive.

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?

Purpose is front-loaded and each sentence carries semantics (levels, replacement, follow, withdraw). It is a single dense paragraph with heavy parentheticals, which hurts scannability slightly, but there is little true filler.

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

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

For a 5-parameter mutation with no output schema, the description covers signal meanings, topics combination, replacement, and withdraw/follow behavior well. The gap is the two periodic signals ('more_often'/'less_often') present in the enum but absent from the prose, plus no mention of what happens on invalid labels.

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 real meaning on top by explaining label syntax (e:/c:/f:/free tags), AND-combination of multiple labels, the broad-vs-narrow level framing, and omit-for-whole-story. The signal enum's 'more_often'/'less_often' values are nonetheless never explained.

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 names a specific verb+resource: 'Give a precise up/down signal on one story of a briefing', enumerating the signal set (more/less/technical/simpler/deeper/shorter/mute/follow). Scope (one story, its typed labels) is clear. It does not explicitly contrast itself with topical siblings like tune_topic, so differentiation is left implicit.

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

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

Explicit when/how guidance: 'topics' cardinality selects broad vs narrow levels, omit for whole story, and 'Sending the same signal again with different topics REPLACES the previous one'. It also routes around the follow case ('with follow use unfollow instead') and explains withdraw. Nothing about selection is left to inference.

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?

Adds substantial context beyond the annotations: it explains that the pause leaves podcast_enabled set to true, and critically that resumption is not immediate but takes effect 'from tomorrow.' The delayed-effect timing is genuinely decision-relevant and not derivable from the structured fields, complementing the idempotentHint.

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

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

Three sentences, front-loaded with the mechanism of the pause before stating the effect and how to check status. The parenthetical adds useful precision rather than waste, though the passage is slightly dense.

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 action tool with no output schema and simple annotations, the description is nearly complete: it explains the trigger, the setting that stays true, the delayed effect, and how to verify state. Only minor gaps remain (e.g., behavior when already active), which idempotentHint largely covers.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. No parameter concerns exist.

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 (resume / 'lifts the pause') and resource (the podcast), and explains the non-obvious nature of the pause (automatic, triggered by inactivity) so the agent understands what is actually being resumed. It is clearly distinguishable from siblings like get_information_diet and get_account, which only report status.

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?

Clearly directs the agent to get_information_diet and get_account to determine whether the podcast is paused, implying the precondition for use. It does not, however, name an explicit alternative to resume_podcast or state when not to call it, so it falls short of full when/when-not guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces this with 'Saving again only refreshes the date.' It adds genuinely new behavior: the saved entry is a snapshot that survives deletion of the briefing, and 'chicca' only applies when the briefing has one. No auth or error behavior is disclosed, so not a 5.

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 short sentences, front-loaded with the core action, with the special-case and idempotency details following. Slightly flowery on the 'chicca' gloss, but no sentence is filler.

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

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

For a two-parameter write tool with no output schema, the description covers the mutation's persistence semantics, idempotency, and the special entry value, while annotations carry the safety profile. Only failure behavior (e.g. invalid entry_id, briefing with no chicca) is left unstated.

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, but the description adds real meaning the schema lacks: it explains what the special entry_id 'chicca' actually is (the archive story of quiet days) and conditions it on the briefing having one. briefing_id semantics are left to 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?

States a specific verb and resource — 'Keep one story of a briefing in the reading list (list_saved)' — and names the destination list, which implicitly separates it from save_for_later (list_read_later) and unsave_entry. The special 'chicca' entry case is also spelled out, so an agent knows exactly what this tool writes.

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?

Usage is implied (keep a story so it persists) but there is no explicit when-to-use guidance or exclusion against the similarly named siblings save_for_later and unsave_entry. The destination list is named, which hints at the distinction, but the agent must infer 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 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?

Annotations already cover idempotence and non-destructiveness, so the bar is lower, yet the description adds real context beyond them: the shared copy is stripped of personal notes and the reader's name, and the podcast episode leaks the reader's name via host greetings, hence the opt-in. That privacy implication is genuinely useful. The idempotency restatement duplicates 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?

Purpose is front-loaded and every clause carries content, but the parenthetical privacy details and the podcast aside make the sentence dense. It is efficient without being padded, though slightly wordy.

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?

There is no output schema, and the description compensates by stating that repeated calls return the same link, giving the agent the key return behavior. Combined with the visibility and privacy notes, an agent has enough to call it correctly; only edge cases like error behavior on an invalid briefing_id are unaddressed.

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 both parameters are already documented. The description echoes the podcast semantics (episode included only when true) and its naming rationale but adds little syntactic or default detail beyond the schema, and says nothing new about briefing_id. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: creating (or reading) the public link of a briefing. It also names the reverse operation, unshare_briefing, so an agent can tell it apart from the update/delete siblings without opening a schema. No sibling does the same thing.

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?

It gives clear operational context: repeating the call is idempotent and unshare_briefing revokes the link, which orients the agent among alternatives. It also frames the podcast decision as the reader's call, guiding parameter choice. It stops short of an explicit when-to-use/when-not statement (e.g., when sharing is warranted vs. generate_briefing).

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

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

Annotations already declare the non-read-only, non-idempotent, non-destructive, closed-world safety profile, so the bar is lower. The description adds genuine behavior beyond that: it persists into future briefings, combining labels via AND leaves the standalone label untouched ("Tesla alone stays as it is"), and "follow" tracks every development of the whole theme. It does not describe reversibility of mute/unmute beyond the action names.

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

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

Front-loaded with the core action and scope, and every clause carries information (sibling routing, topic vs topics semantics). It is a long, em-dash-heavy paragraph, so it is dense rather than elegant, but it avoids filler.

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

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

For a mutation tool with no output schema and only three parameters, the description covers the action semantics, the topic-vs-topics choice, the AND-combination behavior, the persistence into future briefings, and the sibling alternatives. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it clarifies the alternative relationship between `topic` (one key) and `topics` (a list AND-combined, max semantics illustrated with e:tesla+f:soldi), plus given examples of free tags and typed labels. This is useful disambiguation the schema alone leaves implicit.

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 (tune) and resource (a topic or label combination) and precisely describes the scope of change: frequency, technicality, depth, length, muting, following. It explicitly separates itself from rate_briefing_entry (single story follow) and correct_briefing (vague comment), so an agent can distinguish it from siblings without opening any schema.

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?

Gives explicit routing: use this for a precise single-topic or AND-combination change, use rate_briefing_entry with "follow" for one specific story, and correct_briefing for vague comments like "too much crypto lately". Both when-to-use and when-not-to-use are named.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the pin is released, developments stop getting a dedicated entry, and it succeeds even when the originating briefing no longer exists. It does not discuss reversibility or re-following, which keeps it from a 5.

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, both front-loaded: the action and its effect come first, the edge-case justification second. No filler, no restatement of the title.

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 one-parameter, single-object mutation with an idempotency annotation and no output schema, the description covers the action, the effect, the id source, and the key edge case that separates it from its sibling. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance value by telling the agent exactly where to obtain story_id (get_information_diet → followed_stories), matching the schema's own hint. It adds no format details, so it stays below 5.

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 (release/unfollow) and resource (pinned story) and immediately names the source of the id, get_information_diet → followed_stories. It also distinguishes itself from the similar sibling rate_briefing_entry "unfollow", so an agent can pick between them without opening either schema.

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 names the alternative (rate_briefing_entry with the "unfollow" argument) and the condition that selects this tool over it: the briefing may already be gone, since this path does not require the briefing. That is a concrete when-to-use rule rather than implied context.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the agent knows this mutates state safely on repeat. The description is consistent with those hints ('take out') and adds the dual-identification behavior, but says nothing about undoability or required permissions beyond what annotations cover.

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 dense sentence that front-loads the action and then the disambiguating parameters. No filler, no repetition of the title.

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-param, no-output-schema mutation whose safety profile is carried by annotations, the description covers the essential identification contract. The remaining gap is the all-optional parameter set — nothing tells the agent what an empty call does.

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 restates the schema's own guidance ('by its saved id (from list_saved) or by briefing + entry id') without adding format, constraint, or precedence detail beyond the schema — notably not clarifying that all three params are optional or what happens if none is supplied.

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+resource ('take a story out of the reading list') and names the sibling (list_saved) that supplies the id. This makes the operation distinguishable from save_entry/add-to-list siblings. It stops short of an explicit contrast statement, but the purpose is unambiguous.

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

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

The description implies two ways to invoke it (by saved_id or by briefing + entry id), which is context for usage, but it never states when to prefer one mode or when not to call the tool at all. No prerequisites such as confirmation or irreversibility warnings 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the effect is immediate and scoped to the page and audio, clarifying what 'destructive' actually means here. It stops short of saying whether the link can be re-shared or what the response contains.

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 that names the action first and its effect second. Every clause earns its place and there is no filler.

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

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

For a one-parameter, no-output-schema revocation tool with annotations covering the safety profile, the description is nearly sufficient. It could go one step further by noting reversibility (the link can be re-shared) or error behavior when nothing is shared, which is the only remaining 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% for the single briefing_id parameter, including the useful 'Omit for the latest' default note. The description adds nothing about the parameter, so the 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 a specific verb (revoke) and a precise resource (the public link of a briefing), and the clause 'the page and its audio stop answering' makes clear that only the shared link dies, not the briefing itself — a distinction that separates it from delete-style siblings. An agent can tell this is the inverse of share_briefing without opening any schema.

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?

Usage is implied by the verb: use this when a briefing's public link should no longer work. There is no explicit when/when-not guidance and no mention of the sibling share_briefing or of any prerequisite (e.g., that the briefing must currently be shared).

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 declare mutating (readOnlyHint=false), idempotent, non-destructive. The description adds partial-update semantics ('Pass only the keys you want to change') and the global-scope constraint, which are not captured by annotations. However, it doesn't describe return behavior or merge semantics in detail; given annotation coverage, 4 is appropriate.

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

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

Front-loaded with purpose and a thematic enumeration, followed by two crisp operational sentences. The long enumeration overlaps with the schema but aids selection; overall structure is 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 22-parameter mutation tool with no output schema, the description plus annotations and schema cover purpose, usage, and safety. It could mention return values but that is minor; the definition is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 22 parameters thoroughly. The description's prose enumeration adds grouping (podcast, email) but no syntax or format details beyond the schema, 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 a specific verb 'Change' and resource 'how and when the briefing reaches this person', enumerates the settings covered, and distinguishes itself from siblings by naming get_information_diet and tune_topic. An agent can identify scope without opening the schema.

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 instructs to read get_information_diet first, to pass only keys to change, and clarifies these are global settings not per-topic, routing to tune_topic for single topics. Covers when-to-use, prerequisites, and alternatives.

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

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

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.