NicheDB

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

With no annotations provided, the description must disclose behavior itself, and it does: the source is fetched on a schedule, requires a key, and is restricted to admins and Pro users. It also implies creation is the side effect. It could mention expected response or mutation details more explicitly, but the key safety and access behaviors are covered.

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 compact and front-loaded with the core purpose, then adds prerequisite and access context in a single efficient sentence plus a short follow-up. Every clause earns its place, with no filler or repetition.

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 essential operational context: what a source is, the dependency on list_adapters, scheduling behavior, and access restrictions. There is no output schema and no mention of return values, but for a creation tool the key invocation guidance is present. A brief note on the response 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?

Schema coverage is 100%, so the schema already documents all five parameters. The description adds useful cross-tool semantics by explaining that config fields come from list_adapters and that the source is scheduled, which helps the agent understand how adapter, config, and cadence_minutes relate. This goes beyond baseline 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 action: 'Add a source' and specifies what a source is: 'an adapter with a config, fetched on a schedule'. This distinguishes it from sibling tools like create_feed and list_sources by identifying the resource (source) and its core behavior.

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

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

The description gives clear context and a prerequisite: 'Call list_adapters first for the fields.' It also states access requirements ('needs a key; admins and Pro'). It does not explicitly describe when not to use this tool or compare it to alternatives, 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?

No annotations are present, so the description must carry the behavioral burden. It does disclose that a key is required and that 'upcoming' affects date filtering, which adds some context. However, it lacks consequences of creating duplicate feeds, side effects on existing feeds, or what the response will look like—important for a write operation with no annotation support.

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 compact: two sentences, with the main purpose front-loaded and parameter nuances in a single follow-up sentence. Every phrase earns its place, though the parenthetical 'needs a key' is slightly cryptic and the comma-separated list could be clearer to parse.

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 10 parameters, no output schema, and no annotations, the description is adequate but not complete. It explains only a few parameters and mentions a key requirement without specifying what key or where to get it. The high schema coverage fills most gaps, but creation behavior and response format remain undocumented.

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 high at 90%, so the baseline is 3. The description adds value by clarifying that 'Sources, kinds and tags narrow' and that 'upcoming' means only future-dated items are kept—both go beyond the schema's sparse descriptions. It does not redundantly repeat every parameter, only the ones needing explanation.

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

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

The description opens with a specific verb and resource, 'Save a query as a feed', which clearly identifies the operation. It also notes the auth requirement ('needs a key'). It does not explicitly distinguish itself from sibling tools, but the sibling list contains no other create/save operation, so ambiguity is low.

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 intended use case—when you want to persist a query as a feed—but provides no explicit when-or-when-not guidance or mentions of alternatives like list_feeds or feed_items. It is sufficient for an obvious create operation but does not actively route the agent away from related tools.

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

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

With no annotations, the description carries the full burden. It does add behavioral value by stating the result order is newest-first and that pagination uses before_id. It does not explicitly state read-only behavior, error conditions, or return shape, but those are partially inferable for a simple list tool.

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: the first clause states what the tool returns and the ordering, and the second clauses states how to paginate. Every word earns its place with no filler or schema repetition.

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 feed-item listing tool, this is minimally adequate: it identifies the feed, the ordering, and the pagination mechanism. However, with no output schema, it does not describe return values, and the sibling context suggests it could benefit from clarifying when to use it instead of recent_items or search_items.

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 little beyond the schema: before_id is already labeled as a keyset cursor, limit has a default/max, and feed is described as a slug. No additional parameter semantics are provided.

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 as feed-selected items and specifies the ordering as newest-first. It does not use an explicit verb like 'list' and does not name sibling tools, but it is semantically clear enough to be distinguished from list_feeds, recent_items, and get_item.

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

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

The description provides no guidance on when to use this tool versus recent_items, search_items, or get_item. The pagination hint is operational rather than a usage rule or alternative-selection guideline.

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?

With no annotations, the description carries the behavioral disclosure burden. It usefully reveals that a key is required and that channels are restricted to webpush, email, and webhook. However, it does not state side effects, idempotency, what state gets changed, or what happens after following, so the disclosure is only partial.

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: the action and actor come first, followed by a compact channel list. Every phrase carries information and there is no filler or repetition.

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?

Crucial operational context is present: the action, the key requirement, and the supported channels, with parameters fully documented in the schema. Still, there is no output schema and no explanation of what 'following' does, what a successful call returns, or how failures behave, so an agent may need external knowledge to invoke it confidently.

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 value by enumerating the accepted channel values (webpush, email, webhook), which the schema only partially conveys by listing a default. This helps an agent construct valid channel 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?

The description opens with a concrete verb-resource pair ('Follow a feed') and names the necessary actor ('key owner'), which clearly identifies the operation. It does not explicitly differentiate from sibling tools, but none of the siblings are follow-like, so 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 gives an explicit prerequisite ('needs a key') and lists valid channels, which implies when the tool can be used. It does not name alternatives or conditions for choosing another tool, so routing guidance is left mostly 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?

With no annotations, the description carries the full behavioral burden, but it only hints at response depth with 'full adapter payload.' It does not explicitly state that this is a read operation, nor does it mention error behavior, permissions, or side effects.

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

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

The description is very short and contains no filler; the key differentiator 'full adapter payload' is front-loaded. It is efficient, though it reads as a fragment rather than a clear instructional sentence.

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 getter, this is minimally viable: the schema covers the required id and the description signals that the response is a full adapter payload. However, the absence of annotations and output schema leaves gaps around error behavior and usage 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?

The input schema fully documents the single id parameter, so schema coverage is 100%. The description adds no additional meaning about where the id comes from or how it should be formatted.

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 (an item) and a differentiator ('full adapter payload'), and the singular framing makes clear this is a single-item retrieval. It lacks an explicit verb and does not contrast with siblings like feed_items or search_items, 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?

No guidance is given on when to use get_item versus search_items, feed_items, or recent_items. The only hint is the implicit singular 'One item,' which is too weak to route an agent confidently.

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?

No annotations are provided, so the description must carry the full burden. It reveals what the tool returns (adapters and their config fields), but it does not explicitly state that this is a read-only operation or describe how the result is structured. For a list tool this is a moderate gap, not a severe one.

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-loading the tool's purpose and then giving the usage cue. Every word earns its place; 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?

For a zero-parameter tool with no output schema, the description sufficiently conveys what to expect and when to call it. It could add explicit read-only wording or mention the output shape, but the low complexity means these gaps are minor.

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

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

The tool has zero parameters, so the description has nothing to add about parameter meaning. The baseline of 4 applies because there is no parameter documentation 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?

The description clearly identifies the resource (adapters) and the key information returned (config fields for each adapter), which distinguishes it from all sibling tools. It stops short of an explicit verb like 'lists,' but the meaning 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 gives explicit guidance: 'Use before add_source.' This tells an agent the intended context and prerequisite relationship. It does not discuss alternatives or when not to use the tool, but for a simple no-parameter listing tool this is adequate.

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?

No annotations are provided, so the description carries the behavioral burden. It adequately conveys that the tool returns a collection overview with aggregated counts, implying a read-only listing operation. However, it does not disclose details such as whether all collections are returned, count freshness, ordering, or error behavior.

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

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

The description is a single concise phrase with no filler. The resource and the key output attributes are front-loaded, making it immediately scannable.

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 list tool with no output schema, the description provides the essential return information: collections with source, feed, and item counts. It is nearly complete, though it could benefit from explicitly stating that it returns all collections.

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 description does not need to clarify parameter meaning. The baseline of 4 applies because there is no parameter ambiguity to resolve.

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

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

The description clearly identifies the resource as collections/niches and specifies the returned information: source, feed, and item counts. It implies a listing action and is distinguishable from sibling list_feeds and list_sources, though it does not explicitly contrast itself with them.

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 guidance on when to use this tool instead of siblings like list_feeds, list_sources, or stats. The description is a noun phrase describing output rather than conditions or alternatives, so an agent must infer appropriate usage from the name alone.

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?

No annotations are provided, so the description carries the full burden. It discloses a meaningful behavioral detail: items carry their results under the `enrichment` field. It also conveys that the output is scoped to enrichers and their default collection configuration. It does not mention rate limits or auth, but for a simple listing tool 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 compact, two sentences, and front-loaded with the core purpose. It provides useful examples and one key structural detail about the result payload without wasting words.

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

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

For a parameterless listing tool, the description is largely complete. It names the domain, the scope, and where results live. The only minor gap is that it does not explicitly state the return shape (e.g., 'returns a list' or pagination behavior), but the wording strongly implies a list and no output schema is provided.

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 accepts no parameters, so the schema already covers everything. The description adds value by explaining what the returned items will contain, which is the relevant semantic context for an empty-parameter operation.

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 a specific verb ('list') and resource ('enrichers'), and enumerates concrete examples that disambiguate the tool from sibling list tools like list_adapters, list_collections, or list_sources. It also explains what the listing contains beyond the names — which collections enable each enricher by default.

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 purpose is clear enough that an agent can infer when to use it: when information about enrichers and their default collection associations is needed. However, it does not explicitly state when not to use it or name alternatives, though the sibling list provides such context implicitly.

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?

With no annotations, the description carries the full burden. It does disclose useful behavioral traits: only public feeds are listed, results are sorted most-followed-first, and an optional collection filter is supported. However, it does not mention pagination, auth requirements, or the shape of the returned feed objects.

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 short sentences with no filler. The key facts—public scope, ordering, and optional filter—are all included and front-loaded efficiently.

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 list tool, the description covers scope, ordering, and filtering. However, there is no output schema and the description does not explain what the returned feed entries look like or whether any pagination is involved, leaving some uncertainty for an agent.

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

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

Schema coverage is 100% since the only parameter, 'collection', is already described as a collection slug. The description adds that the collection is optional, which is a small but useful clarification beyond the schema. Baseline 3 is appropriate because the schema already documents the parameter.

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

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

The description clearly identifies the resource as public feeds and specifies ordering by follower count, which distinguishes it from sibling tools like feed_items or list_collections. It lacks an explicit verb, but the tool name 'list_feeds' supplies that verb 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?

The description implies usage for browsing public feeds and optionally filtering by collection, but it gives no explicit guidance on when to prefer this tool over siblings such as feed_items or search_items. No exclusions or alternative routing are provided.

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

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

With no annotations, the description carries the behavioral burden. It does reveal useful output context (status, last run, item counts) and the optional collection scoping, but it does not state whether all sources are returned when collection is omitted, nor any ordering, pagination, or side-effect 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?

Two short sentences with no filler; the key output fields and optional filter are front-loaded. Slightly telegraphic because it lacks a main verb, but it is compact and scannable.

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 list tool with one optional parameter and no output schema, the description provides the essential return fields and the filter dimension. It is adequate, though it leaves unspecified details like the default scope when collection 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 coverage is 100%, so the baseline is 3. The description confirms the collection parameter is optional and appears in the same role as the schema example, but does not add substantial meaning beyond what the input schema already states.

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 makes clear the resource (sources) and the output (status, last run, item counts), and the optional collection filter. It lacks an explicit verb and does not explicitly contrast with sibling tools like list_feeds or list_collections, so it stops short of full differentiation.

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

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

No guidance is given on when to choose list_sources over list_feeds, list_collections, or run_source. The only usage hint is the optional collection parameter, which implies filtering, but there are no exclusions or alternative 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?

With no annotations provided, the description carries the full burden of disclosing behavior. It says the result is 'newest items' and that filtering is optional, but it does not explain how multiple filters interact, how pagination via before_id works, whether this is read-only, or what the response looks like. These are meaningful gaps for a tool with no annotation safety signals.

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 one short, front-loaded phrase: 'Newest items' comes first and immediately communicates the core behavior. The optional narrowing detail is compact and every word earns its place.

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

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

Given the rich schema and the straightforward list behavior, the description is minimally viable but leaves gaps. It does not explain filter combination, pagination semantics around before_id, or the item return shape, and with no output schema or annotations an agent has limited additional context to infer these behaviors.

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

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

The input schema already describes all parameters with 100% coverage, so the description does not need to repeat them. It does add the insight that collection, source, and kind act as narrowing filters, though the word 'or' leaves ambiguity about whether filters combine. This matches the baseline for a well-covered 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 that the tool returns the newest items and can be narrowed by collection, source, or kind. It provides a specific resource and intent, making its purpose understandable. However, it does not explicitly differentiate itself from sibling tools like feed_items or search_items, so it falls just 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 'optionally narrowed' implies this tool is for retrieving recent items and that filters are optional, which gives some usage guidance. It does not state when to prefer this over alternatives such as feed_items, search_items, or upcoming, nor does it give any when-not-to-use 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?

With no annotations provided, the description carries the full transparency burden. It discloses that the call bypasses the source's schedule and requires both a key and owner/admin authorization, which are non-obvious behavioral constraints. It does not mention possible side effects, like pulling and storing new items, or failure modes, but it gives meaningful behavioral context beyond the bare schema.

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

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

The description is a single sentence with no filler: the core purpose is front-loaded and the permission/key constraint is appended compactly. Every phrase carries useful information for selecting and invoking the tool.

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

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

For a one-parameter tool with no output schema and no annotations, the description covers the main needs: purpose, timing, prerequisite key, and required role. The only remaining gaps are a small ambiguity around what 'key' means and no mention of return values or error conditions, but these are minor for a simple trigger 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% and the sole parameter, source, is documented as 'Source slug', so the baseline for parameter semantics is appropriate. The description adds a hint that a key is needed, but does not clarify whether that key belongs to the caller or is configured on the source, and it adds no detail about slug format or where to find valid slugs.

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 action (fetch a source), the resource (source), and a clear behavioral differentiator: doing it now instead of waiting for its schedule. This distinguishes run_source from sibling read/list tools such as list_sources or feed_items, which do not trigger a source run.

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 communicates when to use the tool: when an immediate source fetch is needed rather than waiting for the scheduled run. It also states prerequisites (needs a key and owner/admin permission), but it does not explicitly name sibling alternatives or say 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?

No annotations are provided, so the description carries the burden. It does add value by specifying the searched fields (titles, summaries, tags), but it does not disclose ranking behavior, matching semantics, read-only status, or pagination details. Inferred as read-only from 'search', but not explicitly stated.

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 brief sentences with no wasted words. The core function is stated first, and the usage guidance is placed second. Highly scannable for an agent.

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?

Adequate for basic invocation: the required parameter and filter semantics are in the schema, and the description gives usage context. However, there is no output schema and the description does not mention what the response returns or how results are ordered, so some gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds modest value by clarifying that the query applies to full-text over titles, summaries, and tags, but it does not explain `kind`, `limit`, or `collection` 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?

States a specific verb and resource: full-text search over titles, summaries, and tags. This clearly differentiates it from sibling tools like feed_items, recent_items, and get_item, which are not search operations.

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

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

Provides explicit guidance: 'Use this first when you know a name.' This tells the agent when the tool is appropriate, though it does not explicitly name alternatives or state when not to use it.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It names the categories included but never states whether the tool returns counts, detailed records, or some other summary structure. With no output schema, the return shape is undefined, and the description does not even explicitly confirm the operation is read-only.

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 compact sentence that front-loads the tool's scope and wastes no words. It is appropriately concise, though the brevity contributes to some ambiguity about what the tool actually returns.

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 tool, invocation setup is trivial, but the absence of an output schema means the description must explain what the response represents. The category list is helpful, but 'what this deployment holds' does not clearly specify that the result is a summary or count-based stats object. An agent would still be guessing about the response format.

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

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

The tool accepts zero parameters, so the input schema fully covers parameter semantics. The description adds no parameter-specific meaning, but none is needed when there are no parameters. 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?

The description communicates that the tool provides an aggregate view of a deployment's contents, listing five concrete categories (collections, sources, items, items added today, feeds). It lacks an explicit verb like 'returns' or 'counts,' but the name 'stats' combined with the phrasing makes the intended purpose reasonably clear. It does not explicitly differentiate from sibling list tools, though the aggregate nature is subtly implied.

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 guidance on when to use this tool instead of sibling tools like list_feeds, list_sources, or recent_items. An agent must guess whether stats is for counts/summaries and the siblings are for detailed lists. No exclusions, conditions, or alternatives are mentioned.

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

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

With no annotations, the description must carry the behavioral burden. It does disclose the core behaviors: filtering to future-dated items and ordering by soonest first. However, it does not state whether the operation is read-only, how missing dates are handled, whether the horizon is inclusive/exclusive, or any pagination behavior beyond the schema's limit default.

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, information-dense sentence with no filler. The parenthetical examples are useful and the core purpose and ordering are 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 simple list tool this is adequate, but the absence of an output schema and annotations means the agent gets no guidance on response shape or error behavior. It also does not clarify that collection scopes the query, which a caller would need to know 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 baseline is 3. The description adds minimal parameter meaning: 'dated in the future' relates to the days horizon, but it does not explain how limit or collection affect results beyond what the schema already states.

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 indicates the tool returns items dated in the future, sorted soonest first, with examples that clarify scope (releases, launches, deadlines). It distinguishes itself from siblings like recent_items by focusing on future dates, though it lacks an explicit verb such as 'List' or 'Retrieve'.

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

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

No explicit usage guidance is provided: the description does not state when to prefer this tool over recent_items, feed_items, or search_items, nor does it mention any exclusions or prerequisites. The parenthetical examples imply use cases but leave selection reasoning to the agent.

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