NewsJack

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the mutation and safety profile is covered. The description adds one genuinely useful behavior beyond that: feeds are polled every 5 minutes, which sets expectations for how quickly content arrives. It does not say what happens if the URL already exists (relevant given idempotentHint=false), whether the feed is validated on add, or what is returned.

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 with zero redundancy, and the core action is front-loaded before the polling detail. Every sentence earns its place.

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

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

For a simple three-parameter tool with full schema coverage and annotations, the main missing pieces are duplicate-URL behavior and the fact that no output schema exists, so nothing tells the agent what a successful add returns (e.g., an identifier usable with remove_source or toggle_source). That is a real but modest gap for a tool this simple.

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 url, name, and industry_slug are all documented in the schema, and the description adds no syntax or format detail beyond restating that the URL must be an RSS/Atom feed. The defaulted industry_slug and its allowed slug values are left entirely to the schema, which is acceptable but not additive.

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 ('Add a new RSS or Atom feed URL') plus its domain ('automated news monitoring'), which is enough to separate it from remove_source, list_sources, and toggle_source by verb alone. It never explicitly names a sibling or clarifies how it differs from enabling a global source, so it stops short of a 5.

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 'to automated news monitoring' implies the context in which to use it, but there is no explicit when-to-use/when-not guidance and no routing to alternatives. An agent facing the enable_global_source/disable_global_source siblings gets no help deciding whether to register a custom feed or toggle a built-in one.

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, destructiveHint=false, and idempotentHint=true, but the description goes further: it says the Post and its text are preserved in the library, that already-draft Posts are reported unchanged rather than erroring, and that four specific states produce an error. That is real behavioral context beyond the annotation set, not a restatement.

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?

Five short sentences, each carrying distinct load: state transition first, then data-preservation and the inverse tool, then idempotency, then failure states, then id discovery. The most important fact (what the tool does) is front-loaded with 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 single-parameter mutation with no output schema, the description covers everything an agent needs: the transition, non-destructive semantics, idempotency, error conditions, and id sourcing. There is no meaningful gap remaining.

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 schema already specifies the full Post id (not the 8-character prefix) sourced from list_scheduled or schedule_post. The description's 'Find the id with list_scheduled' largely duplicates that. With the schema doing the heavy lifting, 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+resource (cancel a scheduled Post) and the exact state transition it performs: from scheduled/ready back to draft with scheduled time cleared. It also names the sibling tool (schedule_post) that performs the inverse, so the agent can distinguish it 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 covers when to use (Post is scheduled or ready), when not to (publishing, posted, or failed returns an error), how to find the required id (list_scheduled), and how to undo the effect (schedule_post). Alternatives and preconditions are all named rather than inferred.

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, destructiveHint=false and idempotentHint=true, so the safety profile is largely covered. The description still adds genuine context the annotations do not: the mute is scoped to 'this account's feed' rather than affecting the publication globally, and the change is reversible via enable_global_source. It restates idempotency, which is redundant with the annotation, but the account-scoping detail is the important non-obvious behavior.

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

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

Three tight sentences: effect first, identification method second, sibling alternative third. Every clause carries actionable information and the most important scoping fact is front-loaded.

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 toggle with full schema coverage and annotations covering safety and idempotency, the description supplies everything needed: what it affects, how to identify the target, the alternative for custom feeds, and how to undo it. No output schema exists, so the absence of return-value detail is not a gap for this tool.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description's 'Identify it by its exact publication name' largely mirrors the schema's 'Exact name of the global source'. It adds no guidance on industry_slug (default 'music') or on what happens when the name does not match a known publication. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Mute one of NewsJack's built-in publications') plus the concrete effect ('Stories stop appearing in this account's feed'). It explicitly separates itself from the sibling toggle_source and names its inverse enable_global_source, so an agent can route correctly 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 an explicit when-to-use rule (built-in publication) and an explicit when-not-to-use with the alternative named ('For a custom RSS feed the account added itself, use toggle_source with its source_id instead'). Reversibility via enable_global_source is also called out, leaving little 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?

Adds real behavior beyond the annotations: it explains the user-visible effect (stories return to the feed) and the idempotency semantics (unmuting a non-muted publication changes nothing), which clarifies rather than repeats the idempotentHint. It doesn't cover scope limits such as whether re-enabling affects historical stories or per-device state, but a 4 is fair given annotations already declare non-destructive, non-open-world behavior.

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

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

Four short sentences, each doing a distinct job: define the action, direct to the discovery tool, route to the alternative, then disclose idempotency. Nothing is redundant or buried.

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, non-destructive toggle with full schema coverage and no output schema, the description covers purpose, discovery, alternative routing, and idempotent behavior. 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 a meaningful constraint the schema does not: the name must be the same exact name used to mute, implying exact-match lookup rather than fuzzy resolution. Small but genuine added value.

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

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

States a specific verb and resource ("Unmute a built-in publication") and immediately names its inverse (disable_global_source) plus the outcome ("Stories return to this account's feed"). The distinction from toggle_source for custom RSS feeds is made explicit, so an agent can separate it from siblings without reading 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 when-to-use (unmute something previously muted), when-not-to-use (custom RSS feeds go to toggle_source), and where to find candidates (list_sources shows muted ones). All three routing cues an agent needs are present.

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=false, and openWorldHint=true, but the description adds context annotations cannot: the overwrite "cannot be undone from NewsJack," the write uses a server-level TAP_API_KEY rather than a per-user login, it fails when that key is missing or TAP refuses, and it requires the generate:posts scope without consuming a NewsJack allowance. It even names the return payload. The one gap is the absence of any partial-failure guidance (e.g., whether a campaign is created before the goal write fails).

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 and the when-to-call gate are front-loaded, and nearly every sentence carries distinct information (auth model, mutation semantics, return shape, scope, non-idempotency). It is delivered as a single dense paragraph with no structural breaks, which makes the mode-switching rules between content_id/content and campaign_id/new-draft harder to scan than they need to be.

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?

This is an open-world, destructive, non-idempotent write with no output schema, and the description covers everything an agent needs: preconditions, auth model, branch behavior, irreversibility, failure condition, and the shape of the returned receipt. Nothing material is left to the schema or annotations to guess at.

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 would be 3, but the description adds a constraint the schema cannot express: with zero required parameters, at least one of content_id or content must be supplied. It also restates the precedence rule that content_id overrides content and platform and describes what campaign_id does to the target's goal field.

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?

"Send one Jack to a Total Audio Promo (TAP) campaign, creating a new draft campaign or writing into an existing one" gives a specific verb, resource, and the two operating modes. No sibling tool touches TAP, and the description makes that external boundary explicit ("TAP is a separate product"), so an agent can select it unambiguously.

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 states an explicit gate: "only call this when the person has asked for the Jack in TAP," which rules out speculative or default use. It also explains the two input modes (content_id versus content) and the two output modes (campaign_id versus a new draft), including the warning that omitting campaign_id on a repeat call creates another campaign.

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, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety frame is covered. The description adds genuinely new behavior: one generation is consumed from the daily allowance, a draft Post is written to the library, and the new Post id is consumable by schedule_post and export_to_tap. It stops short of stating what happens on a retry or a failed generation given the non-idempotent hint, which is the remaining gap.

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 side effect and return value. Every clause carries load: the content_id contract with schedule_post and export_to_tap and the allowance cost are both facts an agent would otherwise have to discover by trial.

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 takes on the burden and discharges it by naming both return values (Jack text and new Post id). Combined with the quota note and the dry-run routing, nothing an agent needs to invoke this 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 and the schema already documents every parameter including enums. The description adds meaning the schema does not: the Story must be *owned*, and generation runs against the saved voice and output controls, which contextualizes voice_overrides and style beyond their field-level 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 and resource chain: creates a Jack from an owned Story, applies saved voice/output controls, and persists it as a draft Post. It also names the sibling it is not (generate_post_dry_run), so an agent can distinguish the two 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?

Gives an explicit alternative and the exact condition that selects it: use generate_post_dry_run only when you want the text without a library entry. It also discloses that both paths cost the same daily allowance, removing the most likely wrong-selection motive.

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 readOnlyHint=false and idempotentHint=false; the description supplies the non-obvious cost model the agent cannot infer: the preview runs the normal paid model work and consumes one generation allowance, exactly like the real call. It also states the write boundary ('nothing is written to the library') and a concrete downstream consequence (no Post id), which corroborates and enriches the non-idempotent 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?

Four short sentences, front-loaded with what the tool does, then cost, then downstream handling, then the sibling routing rule. There is no filler or redundant restatement of the name.

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 cost-incurring, non-saving variant of generate_post with no output schema, the description covers the behavior, cost, and follow-up workflow well. It is only incomplete on the nested 'voice_overrides' object and the enum parameter, which the agent would have to guess at.

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 description adds no meaning about any of the five parameters; it only refers to the output 'content' conceptually. Schema coverage is 60%, and two of the uncovered parameters are the riskiest: 'style' has an empty description despite a five-value enum, and 'voice_overrides' is a nested object with no description at all. The description does nothing to compensate for those gaps.

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 ('Create a Jack preview') and immediately bounds it ('without saving a Post'), which cleanly separates it from the sibling generate_post. An agent can identify the operation and its output shape (a preview with no Post id) 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 an explicit selection rule against the alternative: 'Prefer generate_post when the Jack will probably be kept,' which implies the inverse for discardable previews. It also names the follow-on path (schedule_post, export_to_tap) for the case where the preview turns out to be worth keeping.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context about what the config contains, but it does not describe the response shape or any auth/rate constraints.

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

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

The description is a single front-loaded sentence with no redundant wording. Every phrase contributes to identifying the resource and its scope.

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 zero-parameter getter with rich annotations, the description identifies the config's scope well enough for selection. It does not detail the return structure, but the listed categories provide adequate context in the absence of an output schema.

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

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

The tool has zero parameters, so the baseline is 4. There are no parameter semantics for the description to clarify beyond the empty schema.

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

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

The description uses a specific verb, "Retrieve," names the resource as the generation config, and enumerates its contents: sampling, length, and additional writing rules. It also scopes the config to when NewsJack creates a Jack, which clearly distinguishes it from the sibling set_generation_config.

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 retrieval verb implies read-only inspection, but there is no explicit when-to-use or when-not-to-use guidance. It also does not name set_generation_config as the alternative for modifying the config, leaving the agent to infer that relationship.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavioral context: this is an observed/cached snapshot, and it can legitimately return an 'unknown' state when no recent probe exists — an agent would otherwise misread an unknown as a failure. It stops short of describing the health states or per-link granularity of the chain.

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

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

One sentence, front-loaded with the primary action and ending with the important caveat. Nothing is redundant or padded.

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 zero-parameter, read-only probe with no output schema, the description covers what is measured and the degenerate 'unknown' case. It leaves the shape of the health report and the set of non-unknown states unspecified, which is a minor gap but not a blocker to 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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the empty schema and the description are consistent.

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 ('Report the most recent observed health of the NewsJack model chain'), which no sibling tool touches. An agent can distinguish it immediately from generation, source-management, and metrics 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?

Usage is only implied by the phrase 'most recent observed health', which signals this reads cached probe results rather than triggering a live check. There is no explicit when-to-use statement, no mention of how it relates to get_usage_metrics, and no stated conditions 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by enumerating the returned content, which matters since there is no output schema, but says nothing about error behavior for missing IDs or size/latency characteristics. Useful but modest 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?

Two sentences, zero filler: the first front-loads what is returned, the second gives the prerequisite. 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 simple one-parameter read tool with full annotation coverage, the description supplies what the agent most needs: the returned fields and how to obtain valid IDs. The lack of output schema is partly compensated by the enumerated return contents; only failure-mode guidance is absent.

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 states it is the unique story identifier obtained from list_stories. The description's 'by ID' phrasing merely restates the schema, adding no format, validation, or edge-case meaning. Baseline 3 applies.

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

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

States a specific verb ('Retrieve') and resource ('story') scoped by ID, and even enumerates the payload (details, summary, metadata, source URL). This clearly separates it from the sibling list_stories, which returns collections rather than a single full record.

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 prerequisite guidance: 'Use list_stories first to obtain valid story IDs,' which routes the agent to the right sibling for discovery. It does not state when-not to use it or what happens with an invalid/stale ID, so it falls short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds genuine behavioral context beyond that: the data is scoped to 'today' and the response pairs observed usage with the account's tier limits, telling the agent what kind of information comes back.

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 sentence with no filler, and the scope ('today's') and the return content ('tier limits') are both front-loaded rather than buried. Nothing in the sentence is redundant with the name.

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 no-parameter, read-only tool with no output schema, the description carries the burden of describing the return value, and it does so at a high level (observed usage plus tier limits). It stops short of specifying units, reset windows, or the shape of the tier-limit comparison, which would be the 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level meaning is missing.

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 ('Retrieve') and names both the resource ('Jack and roast usage') and the accompanying tier limits, plus the time window ('today'). It is clear what the tool returns, though it doesn't explicitly distinguish itself from siblings (none of which are usage-related, so the distinction is implicit rather than stated).

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 resource itself – an agent would call this to check consumption against quota – but there is no explicit when-to-use statement, no mention of call frequency, and no named alternative. Adequate but leaves the agent to infer the trigger condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond that - a null return when the default house voice is active - but says nothing about scoping to the calling user's brand or how missing sections are represented. With no output schema, the return-shape disclosure is thinner than it could be.

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 load-bearing: the first names the resource and its contents, the second states the edge case. Front-loaded and free of 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 parameters and no output schema, the description carries the burden of describing the return value, and it does so at the field-category level plus the null case. It stops short of explaining the shape of those sections or what an agent should do when null is returned, which leaves a small gap for a zero-arg read.

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 and the baseline of 4 applies. No parameter information is needed or missing.

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 ("Retrieve") on a specific resource ("authenticated user brand voice profile") and enumerates the payload contents (tone guidelines, sample posts, forbidden words, style formatting toggles). The name contrast with set_voice_profile and the voice-specific field list let an agent separate it from get_generation_config or the generation tools without opening a 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?

There is no explicit when-to-use statement, no mention of set_voice_profile as the mutation counterpart, and no prerequisites or exclusions. Usage is only implied by the resource being read and the read-only nature of the call.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description reinforces it with 'Read-only' and adds the required manage:schedule scope. It goes further by explaining that 'ready' means nothing posts automatically, which prevents a real misunderstanding. It does not mention pagination limits beyond the param or ordering stability, but the lifecycle semantics carry genuine behavioral value.

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

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

Front-loaded with the core purpose and default behavior, then statuses, then return shape. It is dense but long; the status glossary is justified, though the return-format sentence could be slightly tightened. Every sentence still contributes information.

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

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

No output schema exists, so the description supplies the return contract itself: a numbered summary with truncated ids/text plus structuredContent { count, posts } with named fields. Combined with the scope requirement and status semantics, an agent has everything needed to call and consume this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns a bump by defining each status value's lifecycle meaning (draft = saved with no time set, ready = time passed and awaiting manual publishing, etc.), which the enum labels alone do not convey. It does not restate the limit parameter, but that is fully documented 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?

States a specific verb and resource ('List the signed-in account's Posts from the library'), plus the default filter, the sort order ('ordered by scheduled_for, soonest first, unscheduled last'), and explicitly claims the role of 'the general Post listing tool' when status is 'all'. That distinguishes it from siblings like list_stories and list_sources 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 when-to-use guidance: default returns the scheduled queue, pass status 'all' for every Post. It also routes the agent forward by naming the tools that consume the returned ids (schedule_post, cancel_scheduled, export_to_tap), so the next step is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds modest context about scope (per-account, includes custom feeds and disabled global overrides), but says nothing about ordering, pagination, or result size.

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 with no redundant restatement of the title or annotations. Every clause contributes scope information.

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

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

For a zero-parameter read-only list tool with annotations covering safety, the description says enough: what is listed and what the list includes. No output schema exists, but the enumerated content (feeds and disabled overrides) adequately conveys the return contents.

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 the baseline is 4 and the description correctly implies a full, unfiltered listing with no filtering syntax to document. There is no ambiguity about arguments.

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?

Specific verb ('List') plus resource ('news sources monitored for your account'), and it enumerates what the list includes: custom RSS feeds and disabled global source overrides. That distinguishes it from siblings like add_source, remove_source, toggle_source, and the global-source enable/disable tools.

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

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

The description implies usage (inspect the account's monitored sources) but never states when to use it versus alternatives such as list_stories or the toggle/disable tools. There are no explicit prerequisites or exclusions, leaving the agent to infer routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description still adds meaningful non-schema behavior: the read:stories scope requirement, the authentication error for anonymous callers, that no allowance is consumed, and that only previously scanned Stories in this account are returned. That added context is real value but it sits on top of annotations that already do most of the work, so it lands at a solid 3 rather than higher. Missing are rate limits or limits on how stale scanned Stories can be.

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, followed by return shape, next-step routing, and constraints, so nothing important is buried. It is dense and long-winded in places (a full enumeration of structuredContent fields inside one sentence), which costs it the top mark, but each sentence carries operational information rather than 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 compensates well by spelling out both the readable summary fields and the structuredContent shape, plus count semantics and score scaling. Auth scope, closed-world behavior and the zero-result interpretation are all covered, leaving only minor gaps such as pagination or Story freshness.

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 every parameter including ranges, defaults and the industry slug enum; the baseline of 3 applies. The description contributes only lightly beyond that, mainly the operational note that an empty result should be handled by lowering min_relevance or dropping category, and the relevance-vs-recency sort distinction stated in prose.

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 precise verb and resource (list the signed-in account's scored news Stories) plus the filtering and sorting axes, and explicitly routes to get_story and generate_post as the next steps. An agent can distinguish it from every sibling in the list without opening a 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 concrete when-to-use ('find what is worth writing about today, then pass a Story id to get_story or generate_post') and an explicit when-not ('it does not fetch feeds or search the web'). It even prescribes a recovery action for the empty-result case (lower min_relevance or drop category).

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 conveyed structurally. The description confirms the deletion targets custom (not global) feeds but adds nothing about irreversibility, side effects on scheduled posts, or failure modes for an invalid or global source ID.

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, zero filler, with the action stated first and the prerequisite follow-up second. 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 one-parameter destructive tool with full schema coverage, no output schema, and annotations carrying the safety semantics, the definition covers what an agent needs to call it. A note on what happens to references after deletion would make it complete.

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

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

Schema description coverage is 100% and the single parameter is documented as 'Unique ID of the custom source to delete.' The description reinforces the ID-based addressing and points to list_sources for retrieval, but adds no format or sourcing detail beyond the schema, 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?

The description states a specific verb and resource ('Delete a custom news feed') and the 'custom' qualifier implicitly separates it from global-source siblings such as disable_global_source, although none of those siblings are named 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?

It supplies a concrete prerequisite path by directing the agent to list_sources to obtain a source ID, which is exactly the guidance needed before invoking. It does not state when deletion is inappropriate versus toggle_source or add_source, so it falls short of a full when/when-not treatment.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Does NOT publish or modify content'. It also explains the non-idempotent behavior implicitly by tying evaluation to the 'live news cycle', which accounts for varying results across calls. It stops short of describing latency, cost, or how the score is derived.

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: the first states the action and domain, the second lists return values and the non-mutating constraint. Nothing is wasted and the core purpose is front-loaded.

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 carries the return-value burden and does so by naming the four outputs. For a two-parameter read-only tool this is nearly complete, though it could clarify what a 'timeliness verdict' contains or how the rewrite differs from the input.

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 (post_content and the platform enum with its default) are already fully documented in the schema. The description adds no format, length, or platform-specific guidance beyond that 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?

States a specific verb and resource ('Evaluate a draft social post') plus the domain ('live music industry news cycle'), and enumerates the outputs (feedback, 0-100 score, timeliness verdict, rewrite). This clearly separates it from generate_post and schedule_post siblings.

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 negative guidance 'Does NOT publish or modify content' usefully rules out write intent, but the description never names an alternative or states when to prefer this over generate_post or generate_post_dry_run. Usage is implied rather than directed.

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 non-readOnly, non-idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds the meaningful fact that scheduling operates on a draft with a future timestamp, but says nothing about failure modes an agent would care about (past timestamps, duplicate scheduling given idempotentHint=false, or whether the post publishes immediately if the time has passed).

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, zero filler, with the primary action front-loaded and the input-mode caveat second. Every clause carries 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?

With no output schema, the description leaves the agent guessing what a successful schedule returns (an ID? a confirmation?), and it does not address the notable schema gap that 'platform' is optional despite being described as the target platform. For a 6-parameter mutation with only one required field, more guidance on which combinations are valid would be warranted.

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 the schema does not encode: that 'content' and 'content_id' are alternative input paths for the same underlying object rather than independent fields. It also frames scheduled_for as a future publish target, reinforcing the ISO 8601 schema note.

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 ('Schedule a draft post for publishing') plus the temporal scope ('designated future time'), which cleanly separates it from siblings like generate_post and cancel_scheduled. It stops short of naming any sibling explicitly, so the differentiation is inferential rather than stated.

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 sentence 'Supply content directly or reference existing content_id' gives genuine mode-selection guidance for the two input paths, but there is no guidance on when to prefer this over generate_post or how it relates to cancel_scheduled/list_scheduled. Usage 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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the meaningful scope detail that changes affect future Jacks, but omits whether partial updates overwrite defaults, whether omitted parameters are preserved, and whether in-flight generations are affected.

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 with no filler or redundancy. It is well-sized for the tool, though it could have spent one more clause on update semantics instead of stopping at the high level.

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 three-optional-parameter mutation tool with full schema coverage, existing annotations, and no output schema, the description covers what is needed to call it safely. The remaining gap is merge/replace semantics, which is a moderate rather than blocking omission.

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 each parameter's meaning and defaults are already documented in structured data. The description loosely maps 'sampling' to temperature and 'length' to max_tokens and characterizes extra_rules as writing rules, but adds no format, range, or interaction guidance beyond the schema.

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

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

Names a specific verb (Update) and a concrete resource set (sampling, length, additional writing rules) scoped to 'future Jacks', which clearly separates it from get_generation_config. The only weakness is the unexplained domain term 'Jacks', which an agent may not know maps to generated content.

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 'used for future Jacks' implies this is a persistent configuration write rather than a one-off generation call, which is useful routing signal against generate_post. However, it never states when an agent should prefer this over get_generation_config or whether settings apply only to subsequent calls, leaving usage 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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value with 'Applied to future Jacks', which tells the agent the change is forward-looking and not retroactive. However, it stays silent on the more consequential ambiguity: with eight optional parameters and none required, it never says whether omitted fields are cleared or preserved, nor whether the 'name' parameter upserts an existing profile.

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

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

Two tight sentences with the action front-loaded and the effect ('Applied to future Jacks') appended as a second, distinct clause. Nothing is redundant with the annotations or schema, and every phrase carries 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?

With eight all-optional parameters, no output schema and a write operation, the definition should resolve at least the partial-update question. Annotations cover idempotency and safety but not merge-vs-replace semantics, which is the one thing an agent most needs before invoking a save with a sparse payload. Otherwise the scope of what 'brand voice settings' covers is adequately framed.

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 every parameter is already documented in the schema and the baseline is 3. The parenthetical list mirrors a subset of the schema fields (tone, sample posts, avoid words, emoji/hashtag) but omits name, sign_off and allow_em_dashes, adding no syntax, format or interaction semantics beyond what structured data provides.

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

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

The description uses a specific verb and resource ('Save custom brand voice settings') and enumerates the content domains it governs (tone, sample posts, avoid words, emoji/hashtag rules). It is clearly distinguishable from get_voice_profile by the verb 'Save', but the sibling is never named, so differentiation is implicit rather than stated.

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 agent can infer this is the write counterpart to get_voice_profile and that settings take effect on future generations. There is no explicit when-to-use, no guidance on calling get_voice_profile first to inspect current settings, and no mention of whether this creates a new named profile or updates an existing one.

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 real context beyond the annotations: it only works on custom sources, pausing preserves configuration while remove_source deletes it. The 'reversible and idempotent' sentence largely restates idempotentHint=true, but the scope restriction and the pause-vs-delete contrast are genuinely new behavioral information.

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, then scope, alternatives, and idempotency in a tight sequence; nothing is buried. Minor redundancy in 'setting the same value twice changes nothing,' which repeats the idempotent annotation, but overall it is dense and purposeful.

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 mutation with full schema coverage, rich annotations, and no output schema, the definition covers action, scope, alternatives, reversibility, and distinction from deletion. 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% and both parameters already carry descriptions clarifying true=resume and false=pause, so the schema does the heavy lifting. The description only adds that source_id comes from list_sources/add_source, which is marginal on top of that.

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

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

States a specific verb pair (pause/resume) and resource (the account's own custom RSS sources), and anchors identity to source_id from list_sources. It explicitly separates itself from sibling tools operating on built-in publications (disable_global_source/enable_global_source) and from add_source/remove_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?

Gives the exact when-to-use condition (feeds added with add_source) and names the alternatives for a different case, including the key discriminating detail that those siblings take a publication name instead of source_id. No inference is required to choose the right tool.

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