NicheDB

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

Annotations already declare this is a non-readonly, open-world, non-idempotent, non-destructive write. The description adds real value beyond that: the authorization requirement (key, admin, Pro tier) and the dependency on list_adapters. It omits what happens on a duplicate source or whether a fetch fires immediately after creation, so it is strong but not exhaustive.

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

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

A single sentence with a parenthetical, front-loaded with the action and resource before the prerequisite and the auth caveat. No filler, and every clause carries information an agent needs.

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

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

For a 5-parameter mutation with a nested config object and no output schema, the description covers the hardest part: where valid adapter/config fields come from. Auth and tier gating are also present. What it lacks is any hint of the post-creation behavior or return value, which matters somewhat given there is no output schema.

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

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

Schema coverage is 100% and the parameter descriptions already state that 'adapter' and 'config' values come from list_adapters, with examples and cadence bounds (5-1440). The description's 'call list_adapters first' restates that same guidance rather than adding new semantics, so the 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 ('Add') and resource ('source'), then defines the resource inline as 'an adapter with a config, fetched on a schedule', which disambiguates it from siblings like list_sources, run_source, and list_adapters. An agent can tell what is being created 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?

'Call list_adapters first for the fields' is an explicit prerequisite that routes the agent to the right sibling before invoking. It also names the gating conditions ('needs a key; admins and Pro'). It stops short of naming alternatives or exclusions (e.g., when to use run_source vs. this), so it is clear context but not a full when/when-not map.

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?

Goes well beyond the readOnly/idempotent annotations: it defines the `standing` semantics ('clear only when every list was checked and found nothing'), discloses that SAM.gov and domain reputation checks are conditional ('when keyed', 'when the operator enabled them'), and warns that a name match is not an identity match. That conditional-coverage disclosure is exactly the kind of caveat annotations cannot express. It does not mention rate limits or latency on the multiple external lookups.

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-loads the purpose and the required input correctly, but the enumeration of every provider (OFAC SDN/consolidated, GLEIF, EDGAR, OpenCorporates, SAM.gov, RDAP, Spamhaus/URIBL/SURBL/Safe Browsing) makes the middle a dense run-on clause that is harder to scan than it needs to be for tool selection purposes.

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

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

With no output schema, the description carries the return-shape burden and does so: it names `standing`, `findings`, and the per-section results for each source, plus the caveat on what 'clear' guarantees. Combined with the conditional-source notes, an agent has enough to decide, call, and interpret the tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: `name` is the anchor parameter while `domain`, `state`, `number` and `ein` are optional corroborators, and it clarifies `state` is two letters. This resolves the ambiguity created by the schema declaring zero required parameters, telling the agent what to supply minimally.

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?

Opens with a concrete question-resource framing ('Is a business on anybody's list?') and then names the specific result field (`standing`) plus every data source consulted, so the agent knows this is a business due-diligence/aggregate-risk lookup. It does not explicitly contrast itself with the adjacent `check_domain` or `reputation_lookup` siblings, which is the only thing keeping it off 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?

Usage is implied by 'Give its `name`, and any of `domain`, `state`...' – the agent can infer it needs at least a name. The closing caveat 'A name match is not an identity: confirm against address and identifiers' gives useful interpretation guidance, but there is no explicit when-to-use/when-not or pointer to the alternative tools (check_domain, reputation_lookup) that overlap on domain/risk checks.

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?

Goes well past the annotations (readOnly/openWorld/idempotent) by disclosing the lookup mechanism (per-registry RDAP), the failure modes that produce unknown (no RDAP server, timeout, 429), and the crucial caveat that not_registered does not mean purchasable because reservations and premium pricing exist. It also states that unknown 'is never a yes', which is exactly the kind of interpretation an agent needs.

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, then input forms, then result semantics, then the pricing note. Every sentence carries information, though the result-semantics block is dense enough that a slightly tighter phrasing would read better.

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

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

There is no output schema, so the description has to cover return values, and it does: registered with registrar and expiry, not_registered, or unknown, plus the per-answer cheapest USD price. Nothing essential for a correct call or correct interpretation of results is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds value by explaining how name and tlds combine (bare word plus tlds expands to multiple queries) and by giving concrete examples, which the schema repeats more tersely.

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?

Opens with a specific question-form verb and resource: 'Is a domain name registered? Asks each registry over RDAP.' That names both the operation and the mechanism (RDAP), which distinguishes it from registry-metadata siblings like get_tld, search_tlds, and tld_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?

Explicitly describes the three accepted input shapes (full name, bare word plus tlds, comma-separated list) and what each result class means, which implies when to call it. It stops short of naming an alternative tool or stating exclusions, so it does not reach the when/when-not bar of a 5.

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

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

Annotations already declare the mutation profile (readOnly=false, idempotent=true, non-destructive), so the lower bar applies. The description adds real value beyond that: how ownership is proven (email match or a backlink from the person's site/show page) and that an admin may claim on behalf of an email. It does not cover what happens if proof fails or what the existing claim state becomes.

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

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

Three sentences, front-loaded with the core action and prerequisite, then the proof mechanics, then the admin path. Every sentence carries load, though the parenthetical "(needs a key)" is slightly terse relative to the verification detail that follows.

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 state-changing, non-idempotent-looking claim operation with no output schema, the description explains how a claim qualifies but not what the call returns, what happens on verification failure, or what occurs to a pre-existing owner. These are material gaps for a mutation tool, though the core mechanics are well covered.

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 both parameters are already documented, and the baseline of 3 applies. The description reinforces that 'email' is an admin-only affordance but adds no syntax or edge-case detail (e.g., what ref formats are accepted, precedence when both ref and email are supplied).

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

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

States a specific verb+resource ('Claim a profile as the key owner'), which clearly distinguishes it from siblings like get_profile or update_profile. It does not explicitly name a sibling to differentiate against, but the ownership/claim framing 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?

Adds prerequisites ("needs a key") and an admin path, which implies context for use. However, it does not say when to prefer claim_profile over siblings such as update_profile or search_profiles, leaving the selection to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and non-idempotence, so the write profile is covered. The description adds the auth-ish 'needs a key' note, but says nothing about duplicate-name behavior, whether a feed is created disabled, or what identifying handle comes back. It also omits entirely the geospatial query mode (lat/long/bbox/radius/unit), which is a meaningful behavioral facet of this 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?

A single tight sentence with the core action front-loaded and the qualifiers after it. Every clause maps to actual parameters; no padding.

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 16 parameters and no output schema, the description covers only about a third of the surface and ignores the whole location-based feed option, which is the least self-evident part of the tool. The rich schema compensates for most field-level gaps, but an agent gets no sense of what a call returns or what the created feed is identified by.

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; every parameter including sort, bbox, enrichers and collection already has prose and examples in the schema. The description restates a subset (sources, kinds, tags, q, upcoming) without adding syntax or edge-case detail 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 ('Save a query as a feed') and previews the filter semantics, which is more than a restatement of the name. It does not differentiate from nearby siblings like submit_feed or follow_feed, so an agent must infer which creation-style tool applies.

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 parenthetical '(needs a key)' hints at a prerequisite, and the clauses about sources/kinds/tags/q/upcoming explain narrowing behavior. However there is no explicit when-to-use/when-not-to-use guidance and no routing toward submit_feed or list_feeds as alternatives.

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

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

Annotations already mark it as a non-readonly, non-idempotent, non-destructive write, but the description adds value beyond them: the link is returned only once (so it must be captured immediately), invites are limited per account, and the operation requires owner credentials. That is exactly the kind of consequence an agent needs before calling a non-idempotent write.

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

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

Four short sentences, front-loaded with the action, then constraint, then side effect, then the one-time return caveat. Nothing is padded and each clause carries operational information.

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

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

For a single-optional-parameter tool with no output schema, the description covers action, prerequisites, limits, and the one-shot nature of the returned link. It stops short of describing the return shape (e.g., a URL string vs. an object), which is the one gap given there is no output schema to lean on.

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?

Only one optional parameter (note) exists and the schema documents it at 100% coverage, including an example. The description adds no parameter-level detail, so the schema baseline of 3 applies.

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

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

States a concrete verb+resource ("Make one invite link") and pins the cardinality ("one"), which separates it from the sibling list_invites and from redeem_code. An agent can identify the operation and its actor ("key owner") 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 the precondition ("as the key owner", "Needs a key") and a scarcity context ("a few per account") that tells the agent to be economical. It does not explicitly name when-not-to-use or point to the counterpart tool (redeem_code), so it falls 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.

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

Annotations only flag it as a non-idempotent, non-destructive write; the description goes well beyond them by disclosing the delivery format (signed POSTs, Standard Webhooks + CloudEvents), the https transport requirement, pattern-matching behavior for events, that the signing secret is returned, and that a key is required. That is exactly the extra context an agent needs before invoking a webhook-registration write.

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

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

One dense, front-loaded sentence that leads with the action and resource, then layers in delivery semantics, event patterns, return value, and auth. No wasted words, and every clause carries operational information.

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

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

With no output schema, the description correctly notes that the signing secret is returned, covers auth ('needs a key'), transport (https), and event filtering. It stops short of addressing duplicate-URL behavior or whether a subsequent test_webhook call is expected, which would close the remaining gap for a write tool that is explicitly not idempotent.

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 already 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by naming concrete event types (feed.item.published, feed.followed, feed.created, submission.approved), restating that feed.* patterns work, and clarifying that omitting events registers all events.

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 ('Add') and resource ('account webhook') and immediately characterizes what the webhook does (signed POSTs with Standard Webhooks + CloudEvents). The verb 'Add' cleanly separates it from the sibling update_webhook, delete_webhook, and list_webhooks without needing to name 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?

Implies usage context ('Add an account webhook') and mentions an auth prerequisite ('Needs a key'), but never says when to use this versus update_webhook, test_webhook, or rotate_webhook_secret, nor what happens on a duplicate URL. Guidance exists but is inferred rather than explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description still adds value beyond them by disclosing that the delivery log is removed too — a non-obvious cascade — and that a key is required for auth.

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

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

Two sentences, no filler, with the scope of deletion front-loaded and the auth requirement trailing. Every clause carries information.

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

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

For a one-parameter destructive tool with full annotation coverage and no output schema, the description covers what is deleted and what auth is needed. Missing only the irreversibility/restore story, which matters for a destructiveHint=true operation.

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

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

Schema coverage is 100% and the single property already documents the format with a concrete example ('wh_01JB2X3Y4Z') and its source tool (list_webhooks). The description adds nothing about the id parameter, which is fine given the schema does the work — 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?

Uses a specific verb ('Remove') plus resource ('account webhook') and extends scope to the delivery log, so the agent knows exactly what is affected. It does not explicitly name sibling operations like update_webhook or rotate_webhook_secret, so differentiation comes from the clearly destructive verb rather than from stated contrast.

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?

'Needs a key.' states a prerequisite but gives no when-to-use context, no warning about irreversibility, and no pointer to alternatives such as update_webhook for reversibly disabling a webhook. The agent must infer from the name alone that this is the terminal option.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior. The description adds two genuinely useful behavioral facts: results come newest first by default, and pagination uses a before_id keyset cursor. It says nothing about result volume, failure modes, or how geo filters interact with paging.

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, no filler, with the ordering constraint front-loaded before the paging hint. It is efficient, though the terseness is part of why purpose and usage are under-specified.

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 10 parameters covering geo, distance sorting, limit and offset, this is a moderately complex tool, and the description omits that breadth entirely. The rich schema compensates for most of the parameter gap, but an agent skimming only the description would not know this tool supports distance-based sorting.

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 parameter documentation is already handled. The description reinforces only before_id paging and default ordering; it adds no meaning for the geo, sort, or radius parameters 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?

"What a feed selects" indirectly conveys that it returns the items belonging to a given feed, and "newest first" states the default ordering. However, it never uses a clear verb like "list" or "return items", and it does not distinguish itself from near-siblings such as recent_items, search_items, or 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?

"Page with before_id" gives a paging hint, but there is no guidance on when to use this tool instead of recent_items, search_items, or list_feeds. The agent must infer the selection conditions 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the description's main added value is the miss case: it explicitly returns null when nothing matches, and accepts both /in/ and /company/ URL forms. It does not describe what the returned profile object contains, which is the remaining gap.

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

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

Two short sentences with no filler, and the accepted URL types plus the return value are front-loaded. The phrasing is slightly tangled but nothing is wasted.

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

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

With no output schema, the description says a 'public profile' or null is returned but never characterizes that object's shape or fields. The negative/positive scope and null behavior are present, but the return contract is only partially specified for an open-ended lookup.

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

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

Schema coverage is 100% and the single 'url' param is well documented with an example. The description still adds meaning beyond the schema by broadening the accepted form to company URLs, whereas the schema example only shows a personal /in/ URL.

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 precisely (the public profile a LinkedIn /in/ or /company/ URL resolves to) and implies the lookup verb via 'belongs to'. It distinguishes itself from broader profile tools by scoping to LinkedIn URLs only, though the phrasing is grammatically awkward ('The public profile a LinkedIn profile ... belongs to').

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

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

The sentence 'LinkedIn only: profiles are never looked up by email' gives a clear negative constraint that implicitly routes email-based lookups to search_profiles. However, no alternative tool is named and no positive when-to-use trigger (e.g. 'use when you already have a LinkedIn URL and want to resolve it to a profile') is stated.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the mutation safety profile is covered. The description adds the auth requirement ('as the key owner (needs a key)'), but the 'Channels: webpush, email, webhook' sentence merely restates the schema and it says nothing about what happens on re-follow or the webhook_url dependency.

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 the key constraint front-loaded; nothing is buried. The second sentence is somewhat redundant with the schema's channels description, which keeps it from a 5.

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 annotations present and full schema coverage, the definition is close to adequate, but it omits the conditional dependency (webhook_url is needed when the webhook channel is selected) and any note on re-follow behavior. Those are gaps an agent would hit in practice.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (including channel defaults and webhook_url examples), which sets the baseline at 3. The description adds no parameter meaning beyond that, and the channels enumeration is a duplicate of the schema text.

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

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

The description pairs a specific verb ('Follow') with a specific resource ('feed') and adds the key-owner scoping, so the action is unambiguous. It does not explicitly contrast with siblings like create_feed or list_feeds, but the verb/resource pairing is distinctive enough to route an agent correctly.

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?

'needs a key' communicates a prerequisite, which is useful context for use. However, it gives no when-to-use/when-not guidance and never points to alternatives (e.g., create_webhook for hook management or create_feed for making a new feed), so the selection logic is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only "full adapter payload," with no mention of what happens for a missing/invalid id, whether adapter data can be stale or large, or any cost/latency 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?

It is one short, front-loaded fragment with no waste, but it is thin to the point of near-vacuity — brevity here comes from omission rather than tight editing.

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 is the only place return values could be explained, and "full adapter payload" is left undefined. For a lookup tool with a single required id, the missing not-found behavior and payload shape leave real gaps despite the rich annotations.

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

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

Schema coverage is 100% and the single id parameter is documented with a concrete example ("Numeric item id from any listing, e.g. 81234567"), so the schema carries parameter meaning. The description adds nothing about the id beyond the schema, which is the expected baseline.

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

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

The fragment "One item with its full adapter payload" largely restates the name get_item, without a verb or statement of retrieval semantics. The only distinguishing signal is "full adapter payload," which hints that this returns complete detail rather than a listing row, but the agent gets no explicit statement of 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?

There is no guidance on when to use this instead of the many sibling retrieval tools (search_items, feed_items, recent_items, match_items). Nothing states prerequisites, e.g. that an id must first come from a listing, even though the schema example implies it.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful return-content context by saying the response includes both the parsed view and the OpenProfile.md as served, though it does not describe error behavior or response structure.

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 definition is a single compact sentence with the resource and identifier formats front-loaded. It is efficient, though the phrase 'the parsed view and the OpenProfile.md as served' is somewhat cryptic.

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

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

For a simple read tool with rich annotations and a fully documented single parameter, this is mostly adequate. However, there is no output schema, and the description only vaguely characterizes the return as a parsed view and OpenProfile.md rather than explaining what that contains.

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 schema already documents the `ref` parameter with three examples. The description repeats the accepted id, slug-id, and handle forms without adding format constraints or semantics 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?

The description identifies the tool as retrieving one person by exact reference and names the accepted identifier forms (id, slug-id, handle). It does not explicitly distinguish itself from search_profiles or find_profile_by_linkedin, but the singular-resource scope is clear.

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

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

The accepted identifier forms imply this is for exact lookups rather than searches, but the description never states when to prefer it over search_profiles, find_profile_by_linkedin, or claim_profile. Usage guidance is inferable rather than explicit.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is covered; the description earns credit for disclosing the payload's richness (promotions, privacy, restrictions, historical root dates, change history). It does not say how an unknown or non-existent TLD is handled, which is the notable remaining gap.

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

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

A single front-loaded sentence: the resource is named first, then the returned fields are enumerated compactly in apposition. The long parenthetical price list is dense but each item carries informational value.

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

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

With no output schema, the description is the only place describing return values, and it does so thoroughly across four field families. Missing only edge-case behavior (unknown TLD, whether history is truncated) for a full score.

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?

Only one parameter and schema coverage is 100%, so the schema already explains the label form, dot-optional and xn-- handling. The description adds no parameter-level detail beyond the schema, making the baseline 3 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 resource (a single top-level domain) and enumerates exactly what comes back: type, registry, RDAP server, root dates, registrar prices, change history. The opening 'One top-level domain' implicitly separates it from the list-style search_tlds sibling, though that sibling is never named.

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

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

Usage is implied only: 'One' suggests single-record lookup versus search_tlds, and 'change history' hints at overlap with tld_changes, but neither alternative nor a when-to-use condition is stated. An agent must infer routing from the wording 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the result is deployment-specific and includes per-adapter config field definitions, signaling this is a static introspection/reference call. No pagination or caching caveats, but none are needed for a small config listing.

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

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

Two sentences, zero waste, with the payload description front-loaded and the usage hint second. Nothing could be removed without losing information.

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

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

For a zero-param, read-only introspection tool with no output schema, the description covers what is returned (adapters plus their config fields) and when to call it. Slightly more on the shape of the returned config fields would make it airtight, but it is sufficient to call 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?

Zero parameters, so the baseline of 4 applies. The description's mention of 'config fields each takes' frames what the agent will get back rather than adding parameter detail, which is appropriate here.

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

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

States a specific verb+resource: it enumerates 'every adapter this deployment can run' along with 'the config fields each takes', which tells an agent exactly what the call yields. It is distinguishable from the nearby list_sources/list_enrichers siblings by the 'adapter' resource, though it never explicitly contrasts 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?

'Use before add_source' gives an explicit sequencing condition that routes the agent correctly. It stops short of naming when-not-to-use or alternatives (e.g., list_sources once sources already exist).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered and the bar is lower. The description contributes the useful detail that each entry carries aggregate counts (source, feed, item counts), but says nothing about volume, ordering or pagination.

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

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

One short phrase, front-loaded with the resource and its payload; nothing is padded. It loses a point only because the fragmentary phrasing omits the verb that would make the action unambiguous.

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

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

There is no output schema, so the description is the only place return information can live, and it does sketch the fields (source, feed, item counts). However it omits ordering, result size, and what a "niche" actually is, leaving the agent with a partial picture of the response.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the schema is fully self-sufficient. Baseline of 4 applies for a parameterless tool.

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

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

The description names the resource ("collections (niches)") and what it carries (source, feed and item counts), which is more informative than the bare name. But it is a noun phrase with no verb, so it never states that it *lists* collections, and it offers no differentiation from adjacent list tools such as list_sources, list_feeds or stats.

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 when-to-use guidance, no mention of prerequisites, and no reference to any sibling tool. An agent must infer from the name alone that this is the enumeration call to make before the per-source or per-feed tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds valuable context beyond that: it says the output ties each enricher to the collections that enable it by default, and that per-item results live under the `enrichment` field.

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

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

Two tight sentences with no filler, leading with the resource and its example types before the collection-default detail. The phrasing is a noun phrase rather than an explicit verb ('list'), which slightly softens the front-loaded intent, but nothing is wasted.

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

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

For a parameterless, non-destructive list tool with no output schema, the description covers what is returned (enrichers plus their default collections) and where downstream results appear (`enrichment`). There is no meaningful gap an agent would hit when calling it.

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

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

The tool takes zero parameters and the schema is an empty object at 100% coverage, so there is nothing for the description to disambiguate. The 0-parameter baseline of 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 names a specific resource (enrichers) and enumerates concrete examples (YouTube videos, Wikipedia, repo stats, downloads, company profiles, TL;DRs), so an agent knows exactly what this returns. It does not explicitly distinguish itself from sibling list tools like list_adapters or list_collections, which keeps it out of 5 territory.

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

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

Usage is implied — an agent would call this to discover available enrichers and their default activation per collection — but there is no explicit 'use when' statement, no prerequisites, and no mention of alternatives such as list_collections when the real question is about collections.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds two useful behaviors beyond that: results are limited to public feeds and are ordered by follower count descending. It says nothing about result volume, pagination, or whether the collection filter excludes uncollected feeds.

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 scope/ordering upfront. It is efficient, though the telegraphic style leaves out a verb that would cost almost nothing to include.

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

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

For a single-optional-parameter read tool with annotations covering safety, this is close to sufficient, but with no output schema the description should say what a feed record looks like or whether results are paginated/limited. As written the agent knows the shape of the input but not the response.

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%; the collection slug, its example, and the pointer to list_collections are all documented in the schema. The description's 'optionally one collection' only restates that the parameter is optional, adding no new syntax or semantics.

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

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

The fragment 'Public feeds, most followed first' identifies the resource and its ordering, but never states the action (list/browse) and does not distinguish it from close siblings like feed_items, submit_feed, or create_feed. An agent can guess it returns a catalog of public feeds, but must infer rather than read it.

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?

'Optionally one collection' hints that the tool can be scoped, but there is no statement of when to choose this over feed_items, list_collections, or search. No exclusions, prerequisites, or alternatives are named.

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

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

The annotations already declare this as a safe, read-only, idempotent operation. The description adds useful behavioral context by stating that it requires a key and by describing the returned contents: remaining quota and invite statuses. It does not discuss pagination or ordering, but those gaps are minor for a zero-parameter 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 a single efficient sentence that front-loads the core resource and includes only relevant scoping and prerequisite details. No sentence is redundant or wasted.

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

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

With no parameters, clear annotations, and no output schema, the description supplies the key missing context: authentication requirement and the shape of the returned information. An agent has enough information to select and invoke this tool correctly.

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

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

There are no parameters to document, which meets the baseline of 4. The description appropriately does not invent parameter semantics, and the empty schema is fully consistent with the tool description.

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 and what it returns: the key owner's invites, remaining quota, and per-invite status. It does not explicitly name sibling tools such as create_invite or redeem_code, but the read-oriented status listing is distinct enough to avoid confusion.

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 prerequisite 'Needs a key' provides context for when this tool is callable, and the content implies it is for checking existing invites and quota. However, it gives no explicit guidance on when to use this versus create_invite or redeem_code, nor any exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the return payload shape (status, last run, item counts), which matters because there is no output schema, but says nothing about ordering, pagination, or what 'status' values mean.

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 telegraphic fragments with zero filler, and the return-field summary is front-loaded before the filter caveat. It is efficient, though the fragmentary style costs a little readability.

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

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

For a zero-required-param read tool with 100% schema coverage and annotations covering safety, the description is nearly sufficient. The gap is that no output schema exists, so return values rest entirely on the brief 'status, last run and item counts' phrase, with no detail on shape, ordering, or volume.

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

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

Schema description coverage is 100% and the single parameter is documented with an example ('games') plus a pointer to list_collections. The description's 'Optionally one collection' only restates the optionality the schema already encodes, adding no new syntax or format detail.

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

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

The description names the resource ('Sources') and lists what comes back ('status, last run and item counts'), but it is a sentence fragment with no verb, so the agent infers 'list' from the tool name. It does not distinguish itself from siblings like list_collections, run_source, or add_source.

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

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

'Optionally one collection' implies the filtering behavior, and the schema's parameter hint points at list_collections, so usage is inferable rather than stated. There is no explicit when-to-use, when-not-to-use, or alternative routing in the description itself.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds important context: it explicitly excludes secrets and requires an API key, which are security and auth traits not captured by annotations. It could mention pagination or response format, but for a simple list tool this is sufficient.

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

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

The description is concise (two sentences, 22 words) and front-loads the key information about what is returned. The phrasing is slightly fragmented but every sentence earns its place.

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

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

Given zero parameters, no output schema, and annotations covering safety, the description provides enough context: it states what is returned, what is excluded, and the auth requirement. A minor gap is the lack of mention of ordering or pagination, but for a simple list endpoint this is reasonable.

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 parameter semantics are not applicable. The baseline for 0 parameters is 4, and the description does not need to provide parameter details.

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 webhook endpoints and event types, which is a specific resource. It distinguishes itself from secret-related siblings by noting 'never their secrets', but it does not explicitly contrast with create_webhook, delete_webhook, or webhook_deliveries, leaving some ambiguity about its exact scope.

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 alternatives like webhook_deliveries or list_* siblings. 'Needs a key' indicates authentication but does not help an agent decide when listing webhooks is the right action.

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

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

Annotations already declare the operation as read-only, idempotent and non-destructive. The description adds meaningful behavior beyond the annotations: name cleaning, similarity matching, fixture time windows from 36 hours ago to 7 days ahead, and a 0..1 result score. It does not explain ambiguity resolution or failure cases, so 4 rather than 5.

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

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

The description is dense but appropriately sized for a tool with 12 parameters. It front-loads the core question, then adds input forms, cleaning behavior, matchup handling, scoring and collection guidance. Every sentence contributes information the agent needs.

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 definition covers the main behavior, input normalization, fixture time window, result score and collection selection. With no output schema, it could say more about returned fields beyond score. The schema already documents all parameters, so the description is largely complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful semantics beyond the schema by mapping collection values to content types and explaining how date narrows the fixture time window. Most other parameters such as lat, bbox, radius, sort and limit are left to the schema.

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

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

The description states a specific matching function: it cleans messy media names and matches them by similarity to a title, channel or fixture. It gives concrete input examples and explains matchup handling. It does not distinguish this tool from sibling tools such as search_items, so it falls short of 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?

It clearly explains when to use the collection values: screen for films and TV, channels for television channels, sports for fixtures. It also describes input forms such as file names, release names, playlist entries, and matchups. It does not explicitly name alternative tools or state when not to use this one.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description goes further by disclosing the response payload (area totals, year, measure sets that differ for US vs countries, per-level child counts, largest child at `level`) and the upstream data sources (World Bank, ACS 5-year, GeoNames) — meaningful context beyond structured fields. It omits anything about result caching, rate limits, or data vintage limits.

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 purpose, then argument forms, then return shape, then sources — a logical order with no filler sentences. It runs long and repeats key examples already present in the schema, which is the only reason it is not a 5.

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

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

With no output schema, the description carries the burden of explaining what comes back and does so thoroughly, including the US-vs-country measure split and the child-listing behavior. Remaining gaps are minor: ambiguity handling for `q`, paging semantics, and whether measures are always present for every area.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: the hierarchical key format with examples, the fact that key/zip/q are alternative addressing modes, and the world default when none is supplied. It does not clarify how `q` resolves ambiguity or how `limit`/`offset` interact with the 'largest children' listing beyond what the schema already says.

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 — population and demography drilled from world down to ZIP code — and spells out the three ways to address an area (key, zip, q) plus the no-argument world default. No sibling tool overlaps this domain, so an agent can identify it immediately from the first clause.

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

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

Gives concrete invocation patterns with example keys (us, us-ca-los-angeles, gb-england-london) and explicitly states that omitting all arguments returns the world. It does not state exclusions or failure conditions (e.g. ambiguous place names in q), but there is no competing sibling to route away from, so the guidance is nearly 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description needn't repeat it. The description adds nothing about pagination (before_id keyset cursors), default page size, or the interaction between sort=distance and lat/long/radius, which are the behaviors an agent is most likely to get wrong.

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

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

A single front-loaded sentence with no filler and the primary ordering stated first. It is efficient, though its brevity contributes to the omissions in the other dimensions rather than being purely a virtue.

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

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

This is a 12-parameter tool with an entire geospatial capability (lat/long/radius/bbox/unit, distance sorting) that the description never mentions, plus no output schema to fall back on. An agent reading only the description would not know this tool can do proximity queries or that it is paginated via before_id.

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

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

Schema description coverage is 100%, so every one of the 12 parameters is documented in the schema itself, including enums, defaults, and the antimeridian note for bbox. The description only echoes collection/source/kind and adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a clear resource and ordering ("newest items") plus the optional narrowing dimensions, so an agent knows it is a recency-ordered listing tool. It does not differentiate itself from siblings like search_items, feed_items, or match_items, which is the only thing keeping it from 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 description offers no when-to-use guidance and names no alternative. With search_items, feed_items, match_items, and upcoming all returning items, an agent has to infer that this one is for unfiltered recency browsing rather than keyword search.

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

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

Annotations only declare the mechanical safety profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds real context beyond them: the redemption grants time-based Premium that stacks after any current term, and an API key is required. It stops short of stating what happens to an invalid/expired/already-used code, which matters given idempotentHint=false.

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

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

Three short sentences, front-loaded with the action and resource, then effect, then prerequisite. Every sentence carries distinct information with no padding.

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

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

For a one-parameter, no-output-schema tool this covers the essentials: what it does, what it yields, and the auth requirement. The main omission is failure behavior (expired/reused/invalid codes), which an agent would need in order to interpret errors 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?

With a single parameter at 100% schema coverage, the schema already documents the code format, case-insensitivity, and optional dashes. The description's parenthetical CR-XXXX-XXXX-XXXX-XXXX repeats that information rather than adding new meaning such as where the code comes from or whether whitespace is trimmed.

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 ("Redeem") and a specific resource (a credit code in CR-XXXX format) and immediately explains its effect: days of Premium added after any existing term. No sibling tool in the 40-item list touches code redemption, so the purpose is unmistakable without needing comparative language.

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?

"Needs a key" gives an explicit prerequisite, and "for the key owner" clarifies the account the redemption applies to. There are no alternatives or exclusions to name because this is a single-purpose one-shot action, but it doesn't say what to do if redemption fails or whether a key can be reused.

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

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

Annotations only cover the safe-read profile (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond that: URLs are reduced to host, domains are resolved and each A/AAAA re-checked, parent domains are walked, and lists whose own test entry failed surface in `unknown` rather than counting as a miss. That last point is genuinely non-obvious semantics. It stops short of noting latency or external quota costs of the many live DNSBL queries.

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 lead question is well front-loaded, but the body is one very dense run-on braid of parentheticals listing providers and returned keys. Every clause is substantive, yet it reads as an output-field dump rather than a structured explanation, making it harder to scan than it needs to be.

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

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

There is no output schema, so the description carries the full burden of explaining returns — and it does: `listed`, `score`, `reasons`, `traffic`, `indicators`, `dnsbl`, per-address `addresses`, and `unknown`. It also pre-empts the most likely misinterpretation (absence ≠ clean).

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% for the single parameter, so the baseline is 3. The description does add one detail the schema omits (a URL is silently reduced to its host), which is useful, but for a one-parameter tool the added semantics are thin.

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?

Opens with a specific verb+resource question ('Is an IP address or a domain on a blocklist?') and then enumerates exactly which reputation sources are consulted, so the agent knows this is a blocklist/reputation aggregator. It does not, however, distinguish itself from the sibling `check_domain`, which by name sounds like it overlaps.

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

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

Usage is implied by the framing question and the 'not listed is not the same as clean' caveat, but there is no explicit statement of when to prefer this over `check_domain` or `traffic_list`, and no exclusions or prerequisites.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds genuinely new context: the old secret is invalidated immediately, and the tool returns the new secret (useful given no output schema). It doesn't confirm irreversibility or scope of downstream breakage, but it meaningfully exceeds the annotations.

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

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

Three short clauses, each carrying distinct information (action, side effect, return, prerequisite), front-loaded with the core action. No waste.

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

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

For a single-parameter mutation with full schema coverage and annotations, the description covers impact, return value, and auth need. Only mild gaps remain around reversibility and what happens to in-flight deliveries.

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

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

Schema coverage is 100% and the single 'id' parameter is documented in-schema with an example format, so the description has little to add. Baseline 3 applies.

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

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

States a specific verb and resource ('Replace a webhook signing secret'), which is clearly distinguishable from generic siblings like update_webhook or create_webhook. It stops short of explicitly naming those siblings as alternatives.

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?

'Needs a key' hints at an auth prerequisite, but the description never states when an agent should rotate rather than call update_webhook, nor any conditions/exclusions. Usage is only implied.

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

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

Annotations declare a non-read-only, non-idempotent, open-world write; the description adds genuinely new context by stating the authorization requirement ('needs a key; owner or admin'). It does not disclose what a call costs or that repeated calls each trigger a separate run, which matters given idempotentHint=false.

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

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

One sentence, front-loaded with the action and the motivation, with the permission constraint in parentheses. Nothing 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?

For a one-parameter trigger tool with no output schema and clear annotations, this covers the essentials: what it does, why, and who can call it. What happens after the call (does it return a run id, or is it fire-and-forget?) is left unstated and would be useful given there is no output schema.

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

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

Schema coverage is 100% and the single parameter is well documented with an example slug and a pointer to list_sources. The description adds no additional meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a source') plus the key differentiator — immediate execution rather than waiting for the schedule. An agent can distinguish it from list_sources or add_source, though the description never names those siblings directly (only the schema 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?

Gives a clear trigger condition: use this when you want the source fetched immediately rather than on its schedule. It stops short of stating when not to use it (e.g., repeated calls, quota limits) or naming alternatives explicitly.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the searchable fields and a usage preference, but it does not add deeper behavioral details such as ranking logic, result limits, or pagination. A 3 is appropriate given the annotation coverage.

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

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

The description is two short sentences with zero wasted words, and the purpose is front-loaded before the usage hint. Every sentence earns its place.

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

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

For a search tool with ten optional parameters, rich schema descriptions, and safety annotations, the description gives enough context to understand the tool's role. It does not mention available filters like collection, kind, geo radius, or sort, but those are fully covered by the schema and not strictly necessary 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 all ten parameters are already documented in the input schema. The description does not add parameter-level meaning beyond the searchable fields already named, so the baseline 3 applies.

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

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

The description states a specific verb and resource: full-text search over titles, summaries and tags. It clearly conveys the core function, but it does not explicitly distinguish this tool from siblings like match_items or search_profiles, so it falls 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 sentence 'Use this first when you know a name' gives clear when-to-use guidance and implies priority over other search paths. However, it does not name any alternative tool or state when not to use this one, so it is not fully explicit.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the description only needs to add context. It does: results are merged across multiple source apps, ordered by newest change, and each row carries page, openprofile.md URL, accounts, topics, Broadcast shows, Guest section and published role data. It does not discuss result caps or how pagination works beyond the schema's limit.

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

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

Two sentences, front-loaded with the resource definition before the capability and the return inventory. The long parenthetical-style enumeration of returned fields is dense and full of internal jargon (p0dcasters, OutreachGraph) but each item carries information an agent needs.

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

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

With no output schema, the description correctly takes on the burden of describing the return shape, and all seven parameters are covered by the schema. It leaves minor gaps around result capping/paging when limit is hit and how multiple filters are combined, which matters for a 7-param search tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by linking the returned fields to the filter parameters ('filter on them with title, company, seniority or tags') and revealing the facet tag syntax (title:…, company:…, seniority:…) that the tags array expects. It does not clarify interaction between q and tags or how 'since' combines with ordering.

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 ('People: one entry per person') and explains what the entries are assembled from (OpenProfile.md sources like p0dcasters and OutreachGraph). An agent can distinguish this discovery search from get_profile and find_profile_by_linkedin without opening a schema.

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

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

Gives clear search semantics ('by name, headline or anything in the document; newest change first') and tells the agent which filters to apply for title/company/seniority/tags. It never explicitly names when to prefer a sibling like find_profile_by_linkedin (known LinkedIn URL) or get_profile (known identity), so the alternative-routing is only implied.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description appropriately focuses on domain-specific behavior: default renewal sorting, the promotion rationale, `best` price semantics, facet counts, and the `trap` filter. It adds meaningful context beyond the annotations and schema, though it does not cover pagination or response shape in depth.

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 definition is dense but front-loaded: it establishes the dataset first, then defaults, then key field semantics, then the special `trap` filter. Every sentence carries useful information and there is no redundant restatement of schema details.

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 13-parameter tool with no output schema, the description covers the dataset, major return concepts (`best`, facet counts), default sorting, and filtering semantics. It could say more about the return shape or status/paging behavior, but it is substantially complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining why renewal is the default sort, how `best` behaves with and without `registrar`, and what `trap: true` retains, which goes beyond the schema's field-level descriptions.

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

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

The description clearly establishes the resource and dataset: every label in IANA's root, with type, registry, RDAP server, and registrar pricing. It is distinguishable from singular sibling `get_tld` and change-tracking `tld_changes`, though it never uses an explicit action verb like 'search' or 'list'.

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 intended use of specific filters (`trap`, `registrar`, default renewal sort), but it never says when to use this tool instead of siblings such as `get_tld` or `tld_changes`. Usage is implied through parameter semantics rather than explicit tool-selection guidance.

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

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

Annotations already establish this as a read-only, idempotent, non-destructive, closed-world call, so the safety profile needs no restating. The description adds value by disclosing the metric categories returned — important since there is no output schema — but does not clarify whether these are counts or embedded records.

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 compact sentence that leads with scope ('What this deployment holds') and then enumerates the metrics. No filler, nothing redundant.

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 and no parameters, the description carries the full burden of describing the return value, and it only partially does so — it lists subjects but not whether each is a count, a list, or a nested object. Adequate to select the tool, thin for predicting its output shape.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. No parameter guidance is needed or expected here.

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

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

The description enumerates exactly what the tool reports (collections, sources, items, items added today, feeds), which is far more specific than the bare name 'stats'. It implicitly distinguishes itself from list_* siblings by returning a summary of holdings rather than records, though it never says 'counts' or names a sibling.

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: an agent can infer this is the overview/summary call for the deployment. There is no explicit when-to-use statement and no routing away from alternatives such as list_collections, list_sources, or population, which overlap in subject matter.

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?

Substantially beyond annotations: it discloses that no API key is required, that nothing is fetched until an admin approves, and that approved podcast feeds route to rssamplifier while others become a source here. That review gate and downstream routing materially shape whether an agent should bother submitting. Missing only what happens on rejection or how soon review occurs.

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

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

Three short sentences, front-loaded with the action and scope, then auth, then lifecycle. No sentence is filler: even 'No key needed' answers a precondition an agent would otherwise have to discover from an error.

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 four-parameter public submission tool with no output schema, the description covers the essentials: what is submitted, that no credential is required, and that a human gate blocks fetching. The only gap is the outcome feedback loop (accept/reject notification), which the schema's email field partially implies.

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 and the schema already explains url, note, email, and collection. The description adds marginal value by hinting at the keyless path (echoing the email field) and noting an admin may override collection, but it adds no syntax or format detail 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?

'Suggest an RSS or Atom feed for the index' gives a specific verb (suggest, not create) and resource, and the word 'suggest' implicitly separates it from create_feed. It stops short of naming create_feed or add_source outright, so the agent must infer the distinction from 'an admin reviews every suggestion.'

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 key needed' signals the unauthenticated/public case, which is the main reason to pick this over create_feed. However, it never explicitly states when to use this versus create_feed or add_source, nor any exclusion such as already-indexed feeds.

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

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

Annotations already declare non-readonly, non-idempotent, open-world behavior. The description adds useful context beyond them: a real event is delivered to the customer endpoint immediately and the HTTP status is reported, plus an auth requirement ('needs a key'). It does not describe the event payload shape or any rate/side-effect caveats on the receiving 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 sentences, front-loaded with the action and followed by the observable result. 'Needs a key' is terse but carries a real prerequisite; nothing is redundant.

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

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

For a single-parameter tool with full annotation coverage, the description covers the action, the immediate side effect, the auth prerequisite, and the return value (HTTP status), so no output schema is needed. Only the absence of guidance toward sibling tools like webhook_deliveries keeps it below 5.

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

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

Schema coverage is 100% and the schema already explains the id format (wh_01JB2X3Y4Z) and points to list_webhooks. The description only implies 'one of your endpoints' and adds no syntax beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: sends a webhook.test event to one endpoint and reports the HTTP status. This clearly separates it from create_webhook, update_webhook, and webhook_deliveries, though it never names those siblings 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?

'Send ... now' implies an immediate one-off test rather than a configured recurring delivery, which is implied usage guidance. There is no explicit statement of when not to use it or which sibling to use instead (e.g. webhook_deliveries for past attempts).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restatement. The description usefully adds ordering (newest first) and that each row carries the IANA list version, but says nothing about volume, pagination, or how far back the history goes.

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

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

Two sentences, no filler, with the resource and ordering front-loaded and the differentiator placed last. Every clause earns its place.

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

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

With no output schema, the description should describe the record shape; it names ordering and the version field but not the other fields. It also omits the "returned" change type that the schema's change param allows, so a reader could mistakenly conclude only added/removed events exist.

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

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

Schema coverage is 100% and each of the three params (limit, since, change) carries its own description with examples, so the schema does the heavy lifting. The description adds no syntax or filtering nuances beyond it, leaving this at the 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?

States a concrete resource and scope: TLDs added to or removed from IANA's root, plus ordering (newest first) and included field (IANA list version). An agent can distinguish this from get_tld/search_tlds by the fact that it returns change events rather than lookups, though it never names those siblings 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?

"Nobody else publishes this diff" hints at a unique use case, but there is no explicit when-to-use or when-to-prefer-get_tld/search_tlds/upcoming guidance. Usage is implied by the diff framing rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial value beyond them: the human-review approval pipeline, newest-first ordering, and critically the auth-dependent behavior (100 rows without a key vs. up to 1000 with one, plus offset paging). This is real operational context an agent needs.

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 purpose and provenance lead, then filters, then pagination constraints — logically front-loaded. It is dense but nearly every clause carries information; the reviewer-process aside is slightly verbose but relevant.

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

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

There is no output schema, yet the description explains what is returned (IPs banned for specific categories) and the ordering, plus pagination and auth limits. For a read-only list tool this covers everything an agent needs to call 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: that limit/offset only take effect with an API key and that days filters by recency of observation. It even echoes the category enum values, giving redundancy that helps the agent.

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?

It names a specific resource (the nichedb /traffic blocklist of banned IPs) and spells out what the entries are (exploit, scanning, brute force, spam) and the ordering (newest approvals first). An agent can distinguish this from siblings like reputation_lookup or check_domain 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?

It clearly describes the context in which this tool returns data and what filters are available, plus the reviewer-approval provenance. It does not explicitly route the agent away to a sibling (e.g. vs reputation_lookup) or state exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds the default result order (soonest first), which is useful, but says nothing about pagination, default look-ahead window, or how the geo filters change results.

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

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

One sentence, zero filler, with the resource and the ordering front-loaded. Every clause earns its place.

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

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

For a 9-parameter tool with all-optional params and no output schema, the description omits important framing: the default 30-day window, that lat/long/bbox/radius are optional geo filters, and that collection scopes the search. The schema covers these, but the description alone would leave an agent guessing about defaults.

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 every one of the 9 parameters is documented in the schema, including defaults and constraints, so the baseline is 3. The description adds no parameter-level meaning beyond that.

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

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

States a specific resource and filter: items dated in the future, with concrete examples (releases, launches, deadlines) and the default ordering. It implicitly contrasts with recent_items by scoping to future dates, but never names the sibling, so an agent must infer the split.

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 future-date scope implies when to call it (as opposed to recent_items or search_items), but there is no explicit when-to-use, when-not-to-use, or named alternative. Guidance is inferred from the noun phrase rather than stated.

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

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

Adds substantial context beyond the annotations: it explains that `markdown` performs a whole-document replacement, that individual `identity` values are removed with null and `sections` with the word none, and that written values take precedence over all other sources and persist across re-reads. This is exactly the destructive/idempotent behavior an agent needs, consistent with destructiveHint=true and idempotentHint=true.

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

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

Two sentences, front-loaded with the verb and the auth requirement, then the parameter summary. The long field enumeration is justified by the 11 parameters, though the list could be trimmed since the schema already names them.

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 11-parameter, nested-object, destructive mutation with no output schema, the description covers modes, removal semantics, and precedence well. It leaves one meaningful gap: whether omitting a field leaves the existing value untouched (partial-patch semantics) is only inferable, not stated.

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 contributes the crucial mode distinction the schema does not make explicit: either send a complete `markdown` document or patch individual fields. It also previews the nested-object syntax ("key: value", "name: body"), which helps an agent construct valid nested payloads.

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 an ownership/auth constraint ("you own (needs a key)") that separates it from read-only siblings like get_profile or search_profiles. It never names those siblings explicitly, so the agent must infer the routing rather than being told.

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 prerequisite "needs a key" and the ownership restriction give real usage context, but no explicit alternatives or when-not cases are given (e.g. use claim_profile first, use get_profile to read). Usage is implied rather than prescribed.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the description's added value is the state-reset disclosure ('clears its failure count') and the credential requirement ('Needs a key') — both genuinely beyond the annotations. It stops short of explaining what 'destructive' means here (e.g. that enabled=false pauses all deliveries), which would have made it a 5.

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

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

One front-loaded sentence names the resource, enumerates the mutable fields, and appends the prerequisite. No filler and no repetition of the tool name.

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

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

For a 5-param mutation tool with full schema coverage and annotations, the description covers purpose, fields, auth, and the enabled-reset behavior. The main remaining gap is that the destructive nature of disabling (pause of live deliveries) is never stated in prose, even though the annotation hints at it.

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

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

Schema coverage is 100% and the schema already spells out each param, including that enabled true clears failures. The description only restates those same fields, adding no syntax, format, or inter-parameter semantics for 'id' or 'events' patterns. Baseline 3 applies.

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

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

States a specific verb ('Change') and resource ('an account webhook') plus the exact mutable fields, which clearly separates it from sibling create_webhook, delete_webhook, and rotate_webhook_secret. An agent can identify the operation 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?

'Needs a key' conveys the prerequisite, and the mention of 'enabled (true turns it back on)' implies the re-enable use case. However, there is no explicit guidance on when to prefer this over create_webhook/delete_webhook or on what happens if a webhook is disabled and other fields are changed.

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

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

Beyond the annotations, the description discloses rich behavioral details: the returned OSV fields, the nested `database_specific.openvuln` structure, live EPSS reads from FIRST, CISA KEV semantics, null behavior for checked-and-absent KEV data, `unstated` meaning in AI benchmark results, source attribution per field, and the explicit guarantee that no exploit code is included. These details materially help an agent interpret and trust the response.

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 front-loaded with the core purpose and then efficiently enumerates return fields in a dense but information-bearing manner. It is lengthy and uses a semicolon-heavy structure rather than separate sentences, but given the absence of an output schema, the detail mostly 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?

With no output schema and only safety annotations, the description carries the full burden of explaining what is returned and does so comprehensively, including field names, nested structures, status values, and source attribution. An agent has enough information to call the tool and interpret its response correctly.

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

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

Schema coverage is 100%, so the schema already documents the single `id` parameter, but the description adds substantial semantic value by listing the broad range of accepted vulnerability ID formats including MAL and NDB beyond the schema examples. This helps an agent know that non-CVE identifiers are valid inputs.

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

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

The description states a specific resource and scope: 'Everything known about one vulnerability, as an OpenVuln record (a valid OSV record).' It clearly distinguishes the tool from generic lookup siblings by naming the record format and accepted vulnerability ID families. An agent can immediately understand this returns comprehensive vulnerability data.

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 invocation context by specifying that the agent must provide an `id` and enumerating accepted ID types such as CVE, GHSA, OSV, PYSEC, GO, RUSTSEC, MAL, and NDB. It does not explicitly state when to use this versus alternatives, but the purpose is unambiguous enough that no close sibling competes for the same task.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real context beyond that: the auth prerequisite ('Needs a key') and the fields each record exposes, including last error, which tells the agent this is a debugging/inspection surface.

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 efficient sentence with the resource and scope front-loaded and no filler. 'Needs a key' is terse to the point of mild ambiguity about which key, but it earns its place as an auth warning.

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 only two optional params and full schema coverage, the remaining burden is describing the result set, which the description does by enumerating the returned fields in lieu of an output schema. Ordering/retention semantics for 'recent' are unspecified, a minor gap for a read-only listing tool.

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

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

Schema description coverage is 100%, so both parameters are already documented with types, ranges, defaults and examples. The description's 'for one endpoint, or all of yours' merely restates the id parameter's omit-for-all semantics rather than adding format or edge-case detail, 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?

Names a specific resource (webhook deliveries) and states the returned attributes (status, attempts, last error, payload) plus the two scoping modes. It does not explicitly distinguish itself from siblings such as list_webhooks or test_webhook, so an agent must infer the routing.

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 implicit usage: pass an id for one endpoint, omit it for all of yours, and a key is required. There is no explicit when-not or named alternative (e.g., use test_webhook to send a test delivery), so selection guidance is only partial.

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

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

Annotations already declare read-only/idempotent/open-world, and the description goes well beyond them: it discloses that sellers publish no stock or prices, flags the `sponsored` field, explains `kind` values, and advises calling a shop with the ISBN. This is exactly the kind of caveat an agent needs.

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

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

Front-loaded with the core action, then dense with return-shape and caveat detail. The long retailer list is verbose but conveys real informational content; nothing is filler.

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

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

With no output schema, the description still fully explains the return structure (edition fields, online links with kind/sponsored, inStore with address/phone/hours/distance). An agent can invoke and interpret the result without guessing.

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 tying title to author, clarifying that item is a books-collection id, and restricting zip to US in-store lookups. It complements rather than repeats the schema.

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

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

States a specific resource (book) and outcome (where to buy it), and the description enumerates the exact answer shape (edition + online sellers + in-store). No book-related sibling exists to differentiate from, so the ceiling is a clear but non-differentiating purpose.

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

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

Explicitly explains the three valid input modes (isbn, title+author, item) and the condition that unlocks in-store results (a US zip). It doesn't name exclusions or fallback alternatives, but the usage context is clear for each parameter.

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