BedrockNews

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

Annotations already declare readOnlyHint=true, so the read-only safety is covered. The description adds valuable behavioral context: the return includes a full structured analysis, the fields='grin' option skips the heavy body text, and slash-containing ids must be passed verbatim. These details go beyond the schema and help the agent predict what happens.

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, each carrying distinct information: purpose and return payload, projection usage, and id format. The core purpose is front-loaded, and there is no wasted wording.

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 read-only get-by-id tool with two params and no output schema, the description covers purpose, return structure, parameter usage, and the critical id formatting rule. No information 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 both parameters are already documented. The description adds an example id and clarifies the 'grin' projection's effect ('without the heavy body text'), but this is marginal value over the schema's own 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 states a specific verb and resource ('Fetch one BedrockNews story by id') and details the return payload (transformed article plus GRIN scores, extraction graph, key stats, trajectory, what-to-watch). This clearly distinguishes it from siblings like get_extraction_graph or get_related, which would return only a subset or related stories.

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 gives explicit guidance on when to use the fields='grin' projection to avoid heavy body text and warns that story ids contain slashes and must be passed verbatim. While it doesn't explicitly name alternative tools or say when not to use them, the context is clear and actionable for correct invocation.

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, so the safety profile is covered. The description adds valuable behavioral context: the 'not found' case can mean the story has no graph (culture/research modes or older transforms), which is non-obvious and helps an agent interpret empty results correctly.

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, each earning its place: what it returns, why it matters, and a critical edge-case clarification. The core purpose is front-loaded and there is no filler.

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

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

For a single-parameter read-only tool with no output schema, the description covers the essential semantics: return format, use case, and a key edge case. It doesn't describe the exact node/edge structure, but the absence of an output schema and the tool's simplicity make this acceptable.

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. The description adds the note that ids contain slashes and should be passed verbatim, which is useful, but it doesn't add much beyond the schema's own description. 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?

The description clearly states the tool returns a story's extraction map as graph data (nodes + edges), not a picture, and distinguishes it from a generic 'get' by naming the resource and format. It also differentiates from siblings like get_article by emphasizing the graph artifact.

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

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

The description implies when to use it: when you need the extraction map as structured graph data for re-rendering or analysis. It doesn't explicitly name alternatives or exclusions, but the sibling list and the 'not a picture' clarification provide enough context for an agent to select it appropriately.

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, so the safety profile is covered. The description adds meaningful behavioral context by explaining how results are ranked (editorial-mode match, plumb, source affinity, recency) and that they come from the same section, which goes beyond the annotation. It does not detail error handling or pagination, but for a read-only tool with a simple input schema, this is adequate.

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, focused sentence that states the core purpose upfront and then provides ranking details. It is efficient and free of redundancy, though it could be slightly more structured (e.g., separating the purpose from the ranking criteria) for even faster parsing, but it is well within the 'appropriately sized' range.

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-only tool with two parameters (one required) and no output schema, the description provides sufficient context: it explains what the tool does, how results are determined, and the scope (same section). It does not mention return format or potential errors, but given the low complexity and the presence of readOnlyHint, the agent has enough to call it correctly and interpret the outcome.

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% for both parameters, with id described as 'The source story id' and limit as 'Max related stories (default 4, max 12)'. The description does not add new parameter meaning beyond confirming id refers to the article; it does not elaborate on limit semantics or edge cases. Since the schema fully documents the parameters, the description provides no incremental value, aligning with the baseline score of 3.

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

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

The description clearly states the tool returns related stories for a given article, specifying the resource (BedrockNews stories) and the action (retrieve related). It distinguishes itself from siblings like get_article by focusing on relatedness, and adds ranking criteria (section, editorial-mode match, etc.) that make its purpose unambiguous.

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

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

The description implies usage ('for a given article') but does not explicitly contrast with alternatives or state when not to use it. It provides clear context (same section, ranked) but lacks exclusions or explicit comparison to sibling tools like list_stories or get_extraction_graph, leaving the agent to infer when this tool is the best choice.

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 readOnlyHint annotation already signals safety, and the description confirms read-only behavior by saying it 'returns' metadata and capabilities. It adds useful scope details but does not discuss output size, formatting, or any operational constraints, though annotations reduce the burden.

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 pack in the tool's scope and a clear 'call this first' instruction, with the most important identifier front-loaded. No filler or repetition.

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

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

For a parameter-less, read-only tool the description covers what the tool is, what it returns, and when to invoke it. With no output schema, it could have been more explicit about the returned data shape, but 'capability map (every tool, prompt, and resource)' gives a sufficient mental model.

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 in its schema, so the baseline of 4 applies; the description need not add parameter-level semantics because there is no input to configure.

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?

Identifies a specific verb and resource ('returns BedrockNews metadata') and enumerates the exact content: site description, GRIN/CLAIMS/NOVEL frameworks, terms/attribution, machine-readable surfaces, and the full capability map. This makes it easy to distinguish from sibling tools like get_article or list_stories, which target narrower 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?

'Call this first' provides explicit timing guidance and implies it is the discovery entry point for the API. It does not explicitly say when to prefer a sibling, but for an overview tool that is a reasonable, clear directive.

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, so the safety profile is known. The description confirms the tool returns taxonomy data but adds little behavioral detail beyond that — acceptable for a trivial listing tool, though not rich.

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 conveys the resource, its contents, and its relevance to a sibling tool with zero redundancy. Every element 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 zero-parameter, read-only catalog tool with a clear output described (ids, names, frameworks), nothing an agent needs to call it correctly is missing. The relationship to list_stories is documented, completing the context.

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

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

The tool has zero parameters and schema coverage is 100%, so the description doesn't need to compensate for undocumented inputs. Baseline 4 is appropriate; the description correctly focuses on what the tool returns rather than parameters that don't exist.

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 (the BedrockNews category taxonomy) and its contents (ids, display names, editorial frameworks), making the tool's purpose immediately clear. It is easily distinguished from siblings like get_article or get_site_info, none of which concern a category 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 explicitly ties the ids to 'list_stories' category filter', telling the agent a concrete reason to call this tool. It doesn't state explicit when-not-to-use conditions, but for a simple read-only catalog the usage context is well established.

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, and the description adds useful behavior beyond that: newest-first sorting, cursor pagination, compact brief returns, and title-only substring matching (not full-text search). This is meaningful operational context without contradicting 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?

The description is two dense sentences with no filler. The core purpose is front-loaded, the filter list is compressed into a readable set, and the sibling routing to get_article is included without 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?

For a read-only, filterable list tool with no output schema, the description covers what the tool does, what filters are available, ordering, pagination, and return granularity. It leaves exact brief fields and cursor mechanics to schema/output behavior, but those are minor gaps given the tool's simplicity.

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

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

The input schema already documents all parameters (100% coverage), so the baseline is 3. The description adds value by explaining plumb as an analytical-clarity score, labeling filters as GRIN-aware, expanding editorialMode meanings, and clarifying the title search is a substring match on titles only.

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

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

The description clearly states the tool discovers/list BedrockNews stories and enumerates the filter dimensions (verdict, plumb, editorialMode, category, date, title). It also distinguishes itself from get_article by noting it returns briefs rather than full analysis.

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 gives a clear usage context: use this to find and filter story briefs, with an explicit pointer to get_article for full analysis. It does not explicitly state when not to use sibling tools like list_categories or get_extraction_graph, but the filter and result-type framing makes the intended use obvious.

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