FeedMyAgent

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

Annotations already cover safety (readOnlyHint, destructiveHint) and open-world scope, so the bar is lower. The description still contributes real behavior: result ordering (soonest first), structured date/venue fields, no auth requirement, and the key limitation that city filtering is not server-side but must be done on `event.city_normalized` after the call.

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 sibling routing, then prerequisites and the post-filter caveat — a natural priority order. Dense but every clause carries information an agent would otherwise have to discover by trial.

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

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

For a 6-param optional-everything query tool with an output schema and full annotation coverage, this supplies the missing pieces: ordering semantics, sibling disambiguation, auth cost, and the one behavioral trap (no city filter). Return-value shape is rightly left to the 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%, so baseline is 3; the description goes slightly beyond it by naming the filter dimensions (kind, genre, topic, date range) and by revealing that city is deliberately NOT a parameter and must be applied client-side to `event.city_normalized`. It does not restate enum values or limit bounds, which the schema already carries.

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 ('Find upcoming events') with the domain enumerated (concerts, gigs, meetups, conferences, festivals), plus result ordering ('soonest first') and the filter axes. It also explicitly distinguishes itself from the sibling get_latest, so an agent can pick between them 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?

Explicit when-to-use ('Use this for anything about events') and when-to-use-alternative ('use get_latest with product=events only for a raw newest-first scan'). It adds an operational prerequisite ('Needs no API key') and a workaround for an unsupported filter (city), leaving nothing 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 readOnly=true, destructive=false, openWorld=true, so safety is covered; the description adds genuinely new context — newest-first ordering and 'Needs no API key' (a real auth requirement disclosure). It does not discuss pagination or result volume beyond the schema's default limit, keeping it short of 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?

Two sentences, front-loaded with the primary action and scope, followed by routing guidance. No filler or redundancy.

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 a full output schema, complete annotations, and 100% schema coverage, the description only needs to add orientation and routing, which it does. Partial demerit: the prose mentions tags, source, and product filters but omits the equally relevant `section` parameter, creating a small gap between prose and actual behavior.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the enum semantics for source, product, and section. The description only restates that filtering is optional by tags, source, or product, adding ordering information but nothing about parameter syntax or interaction; 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 ('Get the latest items from the ainews feed'), names the domain (technology, compliance, security news for AI agents), and specifies ordering ('newest first') plus optional filters. It is unmistakable against siblings like query_security_feed or list_products.

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 routes usage: 'Use this to browse or monitor the feed; use query_security_feed when you want items matched to a specific task or topic, and list_products to discover other product streams.' Both the use case and the alternatives with their selecting conditions 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?

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 readOnlyHint, openWorldHint and destructiveHint=false, so the description is not burdened with safety disclosure. It adds useful context beyond the annotations: relevance ranking behavior and "Needs no API key," which removes an auth pre-check the agent would otherwise have to make. Return shape is covered by the output schema, so no credit is lost there.

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 and ranking behavior, and the sibling routing sentence carries real routing value. Slightly run-on and denser than necessary, but 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 annotations, a full output schema, and 100% parameter coverage, the description supplies exactly the missing layer: when to reach for this tool versus its siblings and that no API key is needed. Nothing an agent needs in order to call it correctly is absent.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including the query examples and tag vocabulary guidance. The description reinforces the semantic intent of query but adds no syntax, format, or interaction detail beyond the schema; 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 ("Search the ainews feed") plus the ranking mechanism (relevance to a natural-language query) and the content domain (technology, compliance, security news for AI agents). An agent can distinguish it from get_latest and find_events without opening either schema.

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

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

Explicitly gives the selecting condition ("when you have a task or topic in mind") and names three alternatives with their respective conditions: get_latest for browsing without a query, find_events for the events product, list_products for other streams. Nothing is left 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, 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 only supply the safety flags; the description goes well beyond them by disclosing that the item is created as pending and reviewed by automated classification before publication, that it is additive rather than destructive, and the exact auth requirement (free API key via POST /keys, sent as a Bearer token). These are material behaviors an agent cannot infer from the schema or 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?

Purpose and scope are front-loaded and the sibling routing follows immediately, but the sentence is long and packs auth instructions, moderation behavior, and product cross-references into one dense chain of em-dash clauses. Every element is useful, yet it could be broken up for faster scanning.

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 explanation, and the description still covers the write semantics, moderation delay, auth path, and duplicate-URL constraint. For a three-parameter submission tool, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and the per-property descriptions already explain title formatting, URL duplication conflicts, and public-visibility warnings, so the description need not restate them. The prose adds no parameter-level detail of its own, matching the baseline 3 for rich schemas.

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 ("Submit an incident or signal ... to the ainews feed") and enumerates what counts as an incident. It explicitly distinguishes itself from report_event, so an agent can route correctly 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 explicit when-to-use ("contribute intelligence the feed should know about") and names the sibling to use instead for the adjacent case ("use report_event for upcoming events instead"), plus points to list_products for other product data. Nothing about selection is left 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?

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.