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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false. The description adds real behavioral context beyond them: no API key required, results are sorted soonest-first, and there is no server-side city filter so the agent must post-filter on event.city_normalized. It does not cover pagination/rate limits, but the annotation bar is met.

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

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

Front-loaded with purpose and scope in the first clause, then usage routing, then operational notes. Mostly dense, though the closing instruction to interrogate the human about cities/genres is agent-behavior coaching that sits slightly outside the tool description.

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

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

With an output schema present, return-value explanation is unnecessary, and the annotations plus description cover safety, ordering, auth, and the city-filter gap. The only thing an agent might still wonder about is whether results paginate beyond the limit, which goes unmentioned.

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

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

Schema description coverage is 100%, so the schema already documents from/to, kind, genres, topics, and limit. The description only restates the filter axes in prose and adds no syntax, format, or interaction detail beyond what the schema provides; 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 (find), resource (upcoming events), domain examples (concerts, meetups, conferences), the ordering (soonest first), and the filter dimensions. It explicitly carves out the boundary against the sibling get_latest with product=events, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use ('use this for anything about events'), names the alternative and the narrow condition that selects it ('get_latest with product=events only for a raw newest-first scan'). It also flags the prerequisite that no API key is needed and that city filtering must happen outside the tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety and external-data profile is covered structurally. The description adds useful context beyond that: the feed's content domain, output ordering (newest first), and the auth condition ('Needs no API key'). It does not cover pagination or rate limits, so it is strong but not maximal.

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

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

Two sentences, zero filler, with the core purpose and ordering front-loaded before the routing guidance. Every clause earns its place.

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

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

With an output schema present, return values need not be described, and the annotations carry the safety profile. The description is complete for this tool: purpose, ordering, filters, sibling routing, and auth requirement are all 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 description coverage is 100%, so the schema fully documents tags, limit, source, and product enums and defaults. The description only restates the same filter dimensions (tags, source, product) without adding syntax or edge-case guidance, 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 (get) and resource (latest items from the ainews feed), plus the domain scope (technology, compliance, security news for AI agents) and ordering (newest first). It explicitly names sibling alternatives query_security_feed and list_products, so an agent can differentiate without opening schemas.

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

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

Gives explicit when-to-use ('browse or monitor the feed') and when-not ('use query_security_feed when you want items matched to a specific task or topic'), plus list_products for product discovery. Routing is fully specified.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful context beyond that: 'Needs no API key,' which tells the agent it can call this unauthenticated as a first step. It stops short of mentioning rate limits or response size, 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?

Two sentences, no filler. The purpose and the returned fields are front-loaded, followed immediately by the routing instruction and the auth note, so an agent gets the essential information in the first clause.

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?

An output schema exists, so return values need no further explanation, yet the description still previews the key fields. For a zero-param discovery tool, everything an agent needs (what it returns, when to call it, what to do with the slug, no auth required) is present.

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 clarify and the baseline is 4. The mention of the returned 'slug' field usefully signals the value the agent will later pass as a parameter elsewhere.

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

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

States a specific verb (list) and resource (product streams), then enumerates what each entry contains (slug, name, description, web path, filters, use cases). It is clearly distinguishable from the sibling read tools because it is framed as the discovery step that feeds 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?

Explicitly says when to use it ('Use this first when you are unsure which stream fits your task'), what to do with the result (pass the slug as the product param), and names the two tools that consume it (query_security_feed, get_latest). This is close to ideal routing guidance.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds useful context beyond them: results are relevance-ranked rather than chronological, and no API key is required. It doesn't discuss rate limits or result freshness, but with a full output schema the remaining burden is small.

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: capability first, routing second, a short operational note last. No filler, and the highest-value information is front-loaded.

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

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

With an output schema present, annotations covering the safety profile, and 100% parameter coverage in the schema, the description only needs to cover purpose and routing — both of which it does thoroughly. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents query matching (titles, summaries, tags), tag AND semantics, and the limit default. The description adds only the framing of query as 'what your agent is about to do', which is marginal beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb (Search) and resource (ainews feed), specifies ranking by relevance to a natural-language query, and explicitly contrasts itself with get_latest, find_events, and list_products. An agent can select it without opening any schema.

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

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

Gives an explicit when-to-use condition ('when you have a task or topic in mind') and names three alternatives with the condition that selects each (browse newest, events product, discover other streams). This is textbook routing guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the description's 'write (not read-only), additive, never destructive' mainly repeats structured data. However, it adds genuinely useful context beyond annotations: the created item is 'pending', the write goes through the REST API, and it details API-key acquisition and authorization requirements. This is solid but not exhaustive (e.g., no mention of rate limits or idempotency behavior).

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

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

The description is front-loaded with purpose and usage, then behavior, auth, and required fields. It is mostly efficient, but the 'write (not read-only) that is additive, never destructive' clause largely duplicates the annotations and could be trimmed.

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

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

Given the tool is a write with a nested event object, sibling alternatives, API authentication, and an existing output schema, the description covers what an agent needs: purpose, when to use it, auth procedure, pending state, and required/conditional event fields. Nothing critical for correct invocation appears missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a conditional requirement beyond the schema: 'city and country are required for non-online events.' That conditional semantics is meaningful for correct invocation, though the schema already documents starts_at as required.

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 gives a specific verb+resource ('Submit an upcoming event... to the events product'), lists concrete examples, and explicitly contrasts itself with report_incident. An agent can distinguish this from siblings like find_events and query_security_feed without opening any schema.

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

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

It states when to use this tool ('to contribute event listings') and names the alternative for non-event signals ('use report_incident for non-event signals'). The routing condition is explicit rather than 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=false, destructiveHint=false and idempotentHint=false, so the safety profile is partly given. The description goes further by disclosing the pending-state lifecycle and an automated classification review before publication, which the annotations do not carry. It partially wastes words re-stating 'a write (not read-only) that is additive, never destructive', which is why it is a 4 rather than a 5.

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

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

Three sentences, front-loaded with the core action and followed by sibling differentiation and behavioral notes. The 'a write (not read-only) that is additive, never destructive' clause is redundant against the annotations and could be trimmed.

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?

An output schema exists, so return values need not be explained. Purpose, sibling routing, write semantics and the moderation lifecycle are all covered, and the schema handles parameter detail. Nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%, with each of the three parameters documented in the schema (including the duplicate-URL conflict behavior). The description adds no parameter-level 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?

Specific verb+resource ('Submit an incident ... to the ainews feed') with an explicit enumeration of what qualifies (security advisory, outage, novel attack pattern). It directly names the sibling it is not (report_event) and the condition that separates them, so an agent can disambiguate without opening either schema.

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

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

States when to use ('contribute intelligence the feed should know about') and when not to, routing the agent to report_event for upcoming events. This is explicit alternative-selection guidance rather than implied usage.

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, it discloses the full lifecycle: the request is queued for maintainer review, nothing is ingested until accepted, a repeat request adds a vote rather than a duplicate, and a free API key is required (with the exact acquisition and auth-header format). This is well above the bar set by the write/openWorld 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?

Front-loaded with purpose, then usage, then behaviour, then auth. It is dense but each clause carries distinct information; slightly long for a single paragraph, but no sentence 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?

An output schema exists, so return values need not be explained, and the description covers the two remaining gaps for a mutating open-world tool: auth requirements and the queued/vote semantics. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents kind, title, url, reason and product with enums and defaults. The description reinforces the source/topic distinction but adds no syntax or format detail beyond what the schema provides, 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 (request to start covering) and a precise resource (a source like a feed/site/changelog/calendar, or a topic), and immediately distinguishes the two kinds. It is easy to tell apart from siblings like query_security_feed or report_incident.

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 explicitly names the triggering condition (when query_security_feed, get_latest or find_events return nothing useful, or when you know a primary source) and routes the agent to alternatives (report_incident or report_event for a single item). Both when-to-use and when-to-use-something-else are covered.

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