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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that it queries each registry over RDAP, that 'unknown' can result from no RDAP server, timeouts, or 429s, and that 'not_registered' does not imply the name is for sale. It also discloses that each answer includes a price. This is thorough and goes beyond basic operation, covering edge cases and limitations.

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 dense paragraph but every sentence serves a purpose: purpose, input formats, answer semantics, and a caveat. It is front-loaded with the core question and method. There is no redundant or filler text. The length is justified by the necessary nuance around answer interpretation.

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

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

Given the tool has only 2 parameters, no output schema, and no annotations, the description does a solid job of covering what an agent needs to know: how to format inputs, what the possible outputs are, and what each output means. It mentions the price field but does not detail the exact response structure (e.g., JSON keys). This is a minor gap, but the description is largely sufficient for correct invocation.

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

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

The schema already describes both parameters with examples, and coverage is 100%. The description adds meaning by explaining the relationship between 'name' and 'tlds' (e.g., bare word plus tlds, or full names), which the schema does not fully clarify. It also explains the expected answer types. This adds value beyond the schema, though the schema is already descriptive.

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 clear, specific question 'Is a domain name registered?' and immediately states the method (RDAP). It distinguishes itself from sibling tools like get_tld or search_tlds, which focus on TLD metadata, by focusing on registration status. The scope is explicit and leaves no ambiguity about what the tool does.

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

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

The description provides explicit input formats (full name, bare word with tlds, comma-separated list) and explains the meaning of each possible answer (registered, not_registered, unknown), including caveats like reserved/premium domains. It does not explicitly name alternative tools for when not to use it, but the purpose is clear enough that an agent can infer when to call it. Slightly missing an explicit 'use X instead' but the guidance is strong.

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 does disclose a real behavioral constraint (a key is required) and the verification criteria for success, plus an admin-only escalation path. It omits what happens on failure, whether the claim is reversible, and any conflict/rate-limit behavior for a mutation.

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 action, then the admissibility rules. No filler. Slightly dense jargon but nothing dead weight.

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

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

For a mutation with no annotations and no output schema, the description covers the success criteria and auth requirement reasonably well. It still leaves return/failure semantics and reversibility unstated, so it is adequate but not 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%, so both params are already documented (ref = id/slug/handle, email = admins only). The description adds only that the key is needed and that admins may claim on behalf of an email, which largely restates the schema. Baseline 3 applies when the schema does the work.

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 ("Claim a profile") with an inline constraint about the key. It is clearly distinguishable from get_profile and update_profile. It stops short of a 5 only because the phrase "as the key owner" is domain jargon an agent must infer.

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 explains the conditions under which a claim is valid (matching email, backlink from the person's site/show page, or admin on-behalf-of), which is useful context. However it never says when an agent should invoke this versus update_profile or search_profiles, nor any prerequisites or failure 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, the description carries the full behavioral burden and does disclose one genuine trait, the requirement of a key. It says nothing about visibility defaults, idempotency, or what a re-save does, which is thin for a creation 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?

Compact and front-loaded, opening with the core action before the field hints. The clause-heavy second half is dense but every clause maps to actual schema fields, so little is wasted.

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

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

A 16-parameter creation tool with no annotations and no output schema needs more than three field hints. Spatial parameters (lat/long/bbox/radius), sort, unit, public, enrichers, and the required collection go unaddressed, leaving the agent to rely entirely on the 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?

Schema description coverage is 88%, so the schema already documents most parameters; the description largely paraphrases it ('q is a text match', 'Sources, kinds and tags narrow'). It does add meaning for upcoming, which the schema leaves undocumented. Baseline 3 fits given the high coverage.

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

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

States a concrete verb+resource: 'Save a query as a feed'. This clearly separates it from list_feeds, feed_items, and follow_feed. However, it never distinguishes itself from the close sibling submit_feed, so full marks for differentiation are withheld.

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: '(needs a key)' signals an auth prerequisite, and the field hints imply query-shaping. There is no explicit when-to-use guidance nor any statement of when to prefer submit_feed or follow_feed instead.

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 behavioral burden. It discloses the default ordering ('newest first') and the paging cursor, which is useful, but omits auth requirements, rate limits, whether distance sorting changes results, and what the response contains for a 10-parameter listing endpoint.

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 fragments with zero filler, and the ordering caveat is front-loaded. It is efficient, though arguably so terse that it tips into under-specification rather than true conciseness.

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 10-parameter, 1-required listing tool with no annotations and no output schema, the description is far too thin. It should at minimum name the action, the feed-slug requirement, and how it differs from the other item-retrieval siblings.

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

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

Schema description coverage is 90%, so the schema already documents lat/long pairing, bbox antimeridian behavior, unit, limit, radius, and the before_id cursor constraint. The description's 'Page with before_id' adds no syntax or semantics beyond the schema's own 'Keyset cursor; cannot combine with distance sorting', 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 conveys the resource ('what a feed selects') and a default ordering ('newest first'), but never states an explicit verb such as list or return, so the agent must infer that this is a listing tool. It also gives no differentiation from siblings like recent_items, search_items, or get_item, which is a notable omission in a 21-tool namespace.

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?

'Page with before_id' gives a pagination mechanic but says nothing about when to use this tool versus recent_items, search_items, or get_item. There is no when/when-not guidance and no mention of prerequisites such as needing a valid feed slug.

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 carries the full behavioral burden. It discloses that the tool returns both a parsed view and the raw OpenProfile.md, which is useful output context, but it does not mention read-only nature, auth requirements, error behavior, or what happens when the profile is missing.

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

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

It is very short and has no wasted words, with the identifier forms and return artifacts front-loaded. However, the fragmentary phrasing is less clear than a complete sentence and the colon introduces output details after a noun phrase.

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 low-complexity single-parameter read tool, the description covers the accepted refs and return artifacts. It still leaves gaps around behavior when the profile is not found, permissions, and when to prefer search_profiles, so it is adequate but not 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%, so the parameter is already documented. The description adds the example format `<slug>-<id>` and repeats the handle option, but it does not add syntax rules, validation constraints, or lookup semantics beyond what the schema 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 identifies the resource (one person profile) and the accepted identifier forms, and states that it returns a parsed view plus the served OpenProfile.md. It distinguishes exact lookup from sibling search_profiles implicitly, but lacks an explicit verb such as 'get' or 'fetch'.

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 lists valid reference formats but gives no when-to-use guidance, no explicit alternative to search_profiles, and no exclusions or prerequisites. An agent can infer exact-lookup usage, but the description does not state 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 must carry the behavioral burden. It describes the output contents but does not explicitly state that the operation is read-only, has no side effects, or any error conditions. It does not contradict annotations (none exist), but it also does not fully disclose behavior beyond the data 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?

A single sentence with no wasted words, front-loading the main point and then enumerating the response contents. It is concise, though the list of fields is long; still, it remains efficient.

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

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

With no output schema, the description thoroughly enumerates the expected response fields, giving an agent a clear picture of what data it will receive. For a simple one-parameter tool, this is complete; no additional guidance about pagination or errors seems necessary.

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

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

The schema already documents the tld parameter at 100% coverage, including that Unicode and xn-- forms work. The description does not add extra meaning beyond restating that it targets 'one top-level domain', so it meets the baseline for full schema coverage without adding 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?

The description clearly states the tool retrieves a single top-level domain and enumerates the exact data fields returned (type, registry, RDAP server, root dates, registrar prices, change history). This is specific and distinct from sibling tools like search_tlds (which likely searches) and tld_changes (which likely tracks changes).

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

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

The description implies this is for a single known TLD, but it does not explicitly mention alternatives or when to use search_tlds or tld_changes. It provides clear context but no exclusions, so it stops short of full 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?

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, the description carries the behavioral burden and does well: it discloses normalization/cleaning behavior, similarity matching, the fixture kickoff window (36 hours ago to 7 days ahead, narrowed by date), and that each result carries a 0..1 score. It omits permission/rate-limit or error behavior, but for a read-style resolver this is thorough.

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 question and the example inputs, then behavior, then routing. It is dense and each sentence adds information, though the parenthetical example lists and window rule make it longer than strictly minimal.

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

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

For a 12-parameter, no-output-schema tool, the description covers the semantic core (what it matches, how, the score output, fixture timing) while the well-covered schema documents geospatial, sort, limit and radius params. Nothing critical is missing, though pagination/ranking defaults beyond the score are not discussed.

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 92%, so the baseline is 3, and the description adds beyond it: it explains that date narrows the fixture window, implies year is a preference signal, and ties collection values to collection semantics. The geospatial and sort/limit params are left entirely to the schema.

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

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

The description frames a precise resolvable question ('Which title, channel or fixture is this name?') and states the mechanism: input names are cleaned (year, season/episode, quality tags, playlist decorations) and matched by similarity. This clearly differentiates it from sibling lookup tools like get_item or search_items by scope and intent.

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 routes the agent explicitly: 'Use screen for films and TV, channels for television channels, sports for fixtures,' and explains that matchup strings resolve to fixtures. It lacks explicit when-not-to-use or a named alternative, but the collection-based routing is strong practical 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 burden of behavioral disclosure. It discloses the response shape: the area with population, year, and a list of measures; the count of areas at each level; and the largest children at the requested level. It also names data sources. It does not explicitly state that the operation is read-only, but that is implied by the nature of the tool and the lack of mutation language. Minor gaps like error handling for invalid keys are not covered, but the essential behavior is transparent.

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

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

The description is somewhat long but every sentence contributes value. The first sentence states the purpose, the second details inputs, the third describes outputs, and the fourth cites sources. It front-loads the core function and packs in the necessary specifics without fluff. It is dense but not verbose, appropriate for a tool with six parameters and complex output requirements.

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 there is no output schema, the description must explain what the tool returns, and it does: the area with population, year, measures (listed), count of areas at each level, and largest children. It also covers inputs thoroughly and names sources. It does not explicitly describe pagination behavior beyond the limit/offset parameters, but those are already in the schema. The description is sufficient for an agent to understand the tool's scope and output without additional 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 already provides descriptions for all six parameters, so the baseline is 3. The description adds meaningful context by explaining the hierarchical relationship between key, zip, and q, and by clarifying that no argument means the world. It also elaborates on the level parameter's purpose (country, state, city, zip). This goes beyond the schema's simple examples and helps the agent understand how to combine parameters, so it earns a 4.

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

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

The description clearly states the tool's function: providing population and demographic data for geographic areas from world down to ZIP code. It specifies the resource (population/demography) and the drill-down nature, and it lists concrete input methods (key, zip, q) and output contents (area measures, children). It is distinct from all sibling tools, which focus on feeds, profiles, TLDs, etc., so no confusion arises.

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 instructions on how to specify an area: via a hierarchical key (e.g., us-ca), a US zip, or a place name in q, with no argument meaning the world. It also explains the optional level parameter for listing children. While it does not name alternatives, none of the sibling tools serve a similar purpose, so no comparative guidance is necessary. The usage context is clear and complete.

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, yet it discloses almost nothing: no default limit (30), no pagination behavior, no auth needs, and no mention that the tool also supports geographic radius/bbox search despite four geo parameters in the schema. Only the implicit recency ordering is communicated.

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 tight sentence with the filters front-loaded after the core action. Efficient, though it is arguably too terse given the tool's breadth (under-specification is penalized under completeness rather than here).

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 12-parameter tool with zero annotations and no output schema, a one-line description is inadequate. Geo search, pagination defaults, sort semantics, and the before_id/distance incompatibility are all absent from the prose even though an agent needs that framing to invoke it correctly.

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

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

Schema description coverage is 92%, so the schema already documents params like lat/long/bbox/radius/before_id well. The description adds only the mapping of collection/source/kind filters, which the schema covers anyway; 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 clear resource (items) with an implicit ordering (newest) and optional narrowing filters. An agent can tell it's a recency-ordered listing tool, but it never distinguishes itself from close siblings such as search_items, feed_items, or upcoming.

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 to a collection, source or kind' hints at filter scenarios but gives no when-to-use guidance, no prerequisites, and never names an alternative tool for the non-recency cases (search_items, feed_items). The agent must 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?

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 must carry full behavioral disclosure. It mentions the search fields but omits critical details: no mention of pagination, result ordering, default behavior, or whether results are filtered by permissions. For a search tool with 10 parameters, this leaves significant gaps about how the tool behaves beyond the literal search scope.

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 waste. The primary guidance ('Use this first when you know a name') is front-loaded after the purpose statement, making it easy to scan. 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?

For a 10-parameter search tool with no annotations and no output schema, the description is minimal. It covers the core purpose and a basic usage hint but omits behavioral details like pagination, result ordering, error cases, and how the geo parameters interact. It's adequate for a simple search but incomplete given the tool's complexity.

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 90%, meaning the schema already documents most parameters (e.g., lat/long pairing, bbox format, defaults for limit/radius/unit). The description adds no parameter-specific information beyond the search fields. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

States a specific verb and resource ('Full-text search over titles, summaries and tags'), which clearly distinguishes it from sibling tools like match_items or recent_items. It doesn't explicitly contrast with siblings, but the scope is precise enough that an agent can infer the use case.

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 clear context: 'Use this first when you know a name.' This gives positive guidance on when to use the tool, but doesn't mention when not to use it or name alternative tools for other scenarios (e.g., match_items for fuzzy matching). It's helpful but lacks explicit exclusion criteria 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?

No annotations are provided, so the description carries the full load. It discloses that results are newest-change-first and that each answer includes specific fields (page, URL, accounts, topics, Broadcast shows, Guest section). However, it omits details on result limits, pagination, whether search is case-insensitive, and whether it's read-only. Partial behavioral context is given, but significant gaps remain.

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 are dense and front-loaded, with the core resource definition first and result details second. No filler text. However, the second sentence is a long list of fields that could be slightly more structured, but it remains useful.

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 must convey return values; it does this partially by listing fields. However, for a search tool with no annotations, it lacks important context such as authentication requirements, rate limits, empty-result behavior, and how 'assembled from every app' affects duplicate handling. Adequate but with clear gaps.

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

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

Schema coverage is 100%, so parameters are already well documented. The description adds meaning by explaining that 'q' can match against anything in the document (not just name and headline), which extends the schema's scope. It also mentions 'newest change first', aligning with the 'since' parameter, though it doesn't explicitly tie the two.

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

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

The description clearly states it returns one entry per person assembled from apps serving OpenProfile.md, with an explicit example domain (podcasters from p0dcasters). It distinguishes the resource from search_items and recent_items, but doesn't name a sibling alternative for when other search tools would be better.

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?

Implicit usage is deducible: search by name/headline/document, newest first. However, there is no explicit when-to-use versus search_items or other search tools, and no when-not to use guidance. An agent must infer this from the resource name.

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, and it does a good job: it discloses that results are sorted by renewal by default, that 'best' means cheapest USD across registrars, that 'registrar' switches to that registrar's own currency, that answers carry facet counts, and that 'trap' filters for 2x renewal. It also implies a read-only operation without stating it explicitly. It does not mention pagination limits or rate limits, but the schema already documents limit/offset defaults, so the description adds meaningful behavioral context beyond the 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 compact and information-dense, with no filler. It front-loads the core purpose, then adds the most decision-relevant behavioral details (sort default, price semantics, facet counts, trap filter). Every sentence earns its place, and the structure flows logically from what the tool is to how results behave.

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 search tool with 13 optional parameters and no output schema, the description covers the key behavioral nuances an agent needs: default sort, price interpretation, facet counts, and the trap filter. It does not describe the exact shape of the answer items or how facets are structured, but since there is no output schema, a bit more detail on return format could help. Still, the description is complete enough for an agent to select and invoke the tool correctly for most queries.

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 explaining the semantics of 'best' and 'registrar' (cheapest USD across registrars vs. that registrar's own price in its currency), which the schema does not convey. It also clarifies the default sort rationale and the 'trap' filter's meaning. It does not add detail for every parameter, but the schema already covers them well, so the description's targeted additions are sufficient.

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

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

The description opens with a precise statement of what the tool does: it searches top-level domains from IANA's root, and enumerates the data fields (type, registry, RDAP server, registrar prices). It also distinguishes itself from the sibling get_tld by covering the full set of TLDs with search/filter/sort behavior, and from tld_changes by focusing on current registry data rather than changes. The verb 'search' plus the resource 'top-level domains' is specific and unambiguous.

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

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

The description explains the default sort (renewal) and why, and explains the 'best' and 'registrar' price semantics, which helps an agent decide when to use this tool. It also documents the 'trap' filter. However, it does not explicitly say when to prefer search_tlds over get_tld or tld_changes, nor does it state exclusions like 'use get_tld for a single TLD's full details.' The context is clear but the alternatives are not named.

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

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

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 carries the full burden and does well: it discloses that no key is needed, that an admin reviews every suggestion before any fetch occurs, and what happens downstream (podcast feeds to rssamplifier, others become a source). It does not mention rate limits or what the caller sees in response to a submission.

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 tightly packed sentences with zero waste; the core action and the no-key fact are front-loaded, and the review/downstream routing follows logically.

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 should cover the result of a submission, and it does explain the review flow and downstream destinations. Missing only the immediate return behavior (e.g., whether a confirmation or suggestion ID is returned).

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 url, note, email, and collection. The description adds the useful constraint that a key is not required (relevant to the email parameter) but does not add format details beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (suggest) and resource (RSS/Atom feed for the index), and distinguishes itself from sibling create_feed/add_source by framing the action as a non-committal suggestion subject to admin review. An agent can tell it apart from the direct-creation tools 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?

Clearly states the no-key path and the review workflow, implying this is the right tool when you want to propose rather than directly create. It does not explicitly name create_feed or add_source as the alternatives for direct/privileged creation, so routing is implied rather than spelled out.

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 discloses ordering (newest first), version inclusion, and that it returns added/removed entries. This goes beyond the schema, which only describes parameters. However, it omits mention of the 'returned' change type (listed in the schema) and does not describe the output structure, so it is not fully transparent. Score reflects good but incomplete disclosure.

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

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

The description is two sentences, front-loaded with the core purpose and then a concise differentiator. There is zero waste; every word contributes to understanding what the tool does and why it is unique.

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 lacks an explanation of the 'returned' change value that appears in the schema. It also does not outline what the return items look like beyond mentioning a version. Given the tool's simplicity and optional parameters, this is a moderate gap in completeness, especially for an agent trying to understand all possible change types.

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 each parameter already has a description. The tool description does not add meaning beyond the schema (e.g., it does not explain the 'since' format or the semantics of 'returned'). Since the schema handles parameter documentation, this is a baseline 3.

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

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

The description clearly states the tool lists top-level domains added to or removed from IANA's root, newest first, and includes the version. The unique claim 'Nobody else publishes this diff' differentiates it from siblings like get_tld or search_tlds. The verb and resource are specific and unambiguous.

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

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

The description implies usage: use this when you need historical TLD change information. The differentiating sentence ('Nobody else publishes this diff') helps an agent know this is the go-to for such data, but it does not explicitly mention when not to use it or name alternative tools. Still, context is clear enough for selection.

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 behavioral burden. It discloses future-only scope and soonest-first ordering, but omits read-only status, auth requirements, pagination behavior, and return characteristics. A query tool with zero annotations should say more.

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, front-loaded with the resource and temporal scope, then examples and sort order. Every element earns its place 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 9-parameter query tool with no output schema and no annotations, the description is thin: it gives purpose and ordering but says nothing about filters, defaults, or how results are formed. The schema descriptions carry most parameter semantics, so it is not wholly inadequate, but important contextual 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 89%, so the parameters are already well documented in the schema. The description adds no new parameter meaning or syntax beyond what the schema provides, which is the baseline when schema coverage is high.

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

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

States the resource ('items') and temporal scope ('dated in the future'), with concrete examples and a sort order. It is clear what the tool returns, although it uses no verb and does not name sibling tools like recent_items or search_items to differentiate explicitly.

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 when-to-use, when-not-to-use, or alternative tools are named. The agent must infer that this is for future-dated items rather than recent items, searches, or feed listings.

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 burden and does well: it discloses auth ('needs a key'), replacement semantics for `markdown`, deletion conventions ('null removes', '`none` removes'), and precedence/persistence ('what you write wins over every source and survives every re-read'). It does not describe error behavior or what a successful call returns.

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 purpose in the first clause, then the payload options, with no filler. The second sentence is dense but each element (precedence, persistence) earns its place; minor packing of many field names into one 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 an 8-parameter mutation tool with nested objects, no annotations, and no output schema, the description covers auth, replacement/deletion semantics, and precedence. The main remaining gap is return/confirmation behavior and whether unspecified fields are preserved, which an agent would have to infer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it frames the parameters as an either/or (send a full `markdown` document OR individual fields) and explains what replacement means for each. This goes beyond the per-field descriptions 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 ('Edit a profile') plus the scoping constraint 'you own', which separates it from claim_profile, get_profile and search_profiles in the sibling set. An agent can tell what this does without opening the schema.

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

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

Gives a clear precondition ('needs a key', 'a profile you own'), which sets the context for use. It does not name an explicit alternative or when-not condition (e.g. use claim_profile if you don't own one), so it stops short of full routing guidance.

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