Stable News

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

Beyond the annotations (readOnlyHint, idempotent, non-destructive), the description discloses the important behavior that nothing is persisted here — save_brief with the new `confirm` is what keeps it — which explains why a mutating-sounding tool is marked read-only. It also notes the result includes `changes` diffed against the caller's current brief. The remaining gap is how the amendment sentence is supplied.

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 only two sentences, but they are dense, ungrammatical, and not front-loaded — the core action appears inside a subordinate clause. Brevity is achieved at the cost of parseability rather than through 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?

Annotations and an output schema cover safety and return shape, and the description correctly adds the non-persistence rule. Still, for a 2-parameter tool with 50% schema coverage, the description fails to explain the `language` parameter or how the amendment sentence relates to the `brief` payload.

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 only 50%: `brief` is documented in the schema while `language` (enum en/pl, default en) is not described anywhere. The description mentions 'one sentence of the reader's' but never clarifies whether `brief` is the sentence, the full amended brief, or the record to be amended, leaving the required parameter semantically ambiguous.

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 does convey a verb (amend) plus a resource (the brief) via one reader sentence, and it names related siblings (set_brief, save_brief). But the sentence is garbled and back-loaded, so the actual operation must be parsed out of fragments like 'compiled as set_brief does' rather than stated directly.

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 implicit routing: amending differs from set_brief's full compile, and persisting requires save_brief with the new `confirm`. However, no explicit when-to-use / when-not-to-use statement or prerequisites are given, so the agent must infer the workflow chain.

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 description says "the choice put in the record, which is compiled again," which reads as recording an answer and recompiling a record — a write. Annotations declare readOnlyHint=true and destructiveHint=false, directly conflicting with that reading. Even reading it charitably, key behavior (whether re-answering overwrites a previous choice, what authorization is needed) is unstated.

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 short, but the single sentence is a cramped inverted construction with two colons-worth of meaning compressed into it, so the key action is not front-loaded. The final clause "which is compiled again" adds words without adding clarity.

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. However, for a call that gates a brief's record, the description never says what changes after an answer, whether previous answers are kept, or why the record is recompiled — gaps the annotations actively worsen by claiming a read-only profile.

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 75%, so the baseline is 3. The description gestures at the brief and the choice but adds nothing about `language` (its enum, its default, or its effect on the answer) and no format detail beyond what the schema already documents.

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 question set_brief asked, answered" implies a verb (answer) and a resource (a question inside a brief), and naming set_brief gives a routing hook. But the elliptical, inverted phrasing and the opaque trailing clause "which is compiled again" leave the actual effect ambiguous — it is unclear whether the choice is written, validated, or merely echoed.

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?

set_brief is named as the source of the question, which hints at the workflow, but there is no explicit when-to-use statement and no mention of siblings that could be confused with it (amend_brief, save_brief, rehearse_brief, forget_brief). No exclusions or preconditions are given.

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 readOnlyHint=false, but the description adds meaningful behavior beyond them: 'Their history stays on the site' clarifies what is preserved, and 'nothing draws their morning but the world's' describes the resulting morning experience. This is useful behavioral context for a destructive action.

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 short, but the poetic construction ('nothing draws their morning but the world's') obscures meaning rather than front-loading the operational condition in plain language. It is concise but not as clear as it could 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?

For a zero-parameter destructive action with an output schema and annotations, the description covers the essential effect and data retention. The ambiguous morning sentence leaves minor uncertainty, but the agent can still understand what the tool does and when to call 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 has zero parameters, so there is no parameter semantics burden and the baseline score 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 phrase 'The reader's brief dropped' communicates removal of the brief, and the tool name reinforces it, but the metaphorical wording avoids a direct verb like 'delete' and does not explicitly contrast with save_brief or amend_brief. The intent is inferable but not crisp.

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

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

The description gives an explicit condition: 'only when they asked for that in words,' which tells the agent to invoke this only on explicit user request. It does not name alternative tools, but the when-to-use exclusion is clear.

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, closed-world behavior. The description adds substantive context beyond them: the reader's-own fallback and its `own` readiness note, `date` defaulting to latest, and `audio` enabling a read-aloud version. It stops short of details like response size or error behavior, but against the annotation baseline this is strong disclosure.

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

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

The description is a single dense paragraph that front-loads the resource and then lists its contents. The long nested sentence is information-rich and wastes little space, but it is somewhat hard to parse on first read.

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 three-optional-parameter read tool with no output schema, the description covers what is returned, the default edition and date behavior, and the effect of `audio`. It is largely complete; minor gaps are how the `own` readiness note appears and what happens with invalid editions.

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 0%, so the description must carry parameter meaning, and it does: `edition` names public editions world/pl/us and controls the fallback, `date` specifies YYYY-MM-DD with latest as default, and `audio` adds read-aloud output. It nearly fully compensates for the schema gap, though it does not state error behavior for invalid edition values.

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 a concrete resource — the day's edition — and enumerates what it contains: sections, countries, subject, score, mains, story page, outlet, and reading context. This lets an agent understand the tool's output without opening anything else. It does not explicitly contrast itself with siblings such as top or my_brief, which keeps 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?

It provides useful default behavior: no `edition` selects the reader's own edition, falling back to World, and `edition` accepts world, pl, or us. However, it gives no explicit guidance about when to choose this tool over siblings like top, search, or my_brief, so usage is only implied by the resource description.

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, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds only a vague hint that results include user-supplied words and credits, which the output schema already conveys, and says nothing about scoping, empty results, or ordering.

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 short, but the convoluted possessive construction ("theirs over the edition's") makes it harder to parse than a plain sentence and front-loads no actionable 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?

An output schema exists, so return values need not be spelled out, but with a user-specific 'my_' read tool and an undocumented parameter the description should at minimum state what is listed and how edition scopes it. Neither is present, leaving the definition inadequate 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 0% for the single 'edition' parameter with default 'world', so the description must supply the meaning of edition values. It alludes to "the reader's edition" versus "the edition's" but never explains valid values, the default, or what changes when edition is set.

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 is a metaphor ("Every magnet that draws the reader's edition, theirs over the edition's") that never names a concrete verb or resource, so the agent must guess this returns the caller's saved interests for an edition. It effectively restates the name/title in figurative language rather than specifying an operation, and it does not distinguish itself from siblings like save_interest, my_brief, or top.

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 exclusions, and no mention of the obvious alternative save_interest (the write counterpart) or other listing tools. The agent is given nothing to route on beyond a cryptic one-liner.

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 useful behavior beyond that: results come 'from the pool alone' (no external fetch), nothing is persisted ('nothing is saved'), and empty lanes are explicitly reported ('a quiet lane says so').

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 single run-on sentence is dense and poetic rather than front-loaded, with phrases like 'the main it was ranked by' forcing the reader to decode intent. It is short in word count but poorly structured for an agent scanning for purpose and behavior.

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 annotations cover safety. The description still leaves 'lane' undefined and does not clarify how the language parameter affects output or how this tool relates to morning/my_brief, so it is only adequately complete for a three-parameter 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 67%; the schema itself explains the brief format and resolution of plain names, and days is self-documented. The description only echoes the time window ('the last days') and adds no meaning for the language parameter, so it adds marginal value beyond the structured 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 conveys a dry-run preview: 'the mornings of the last days the brief would have given, lane by lane' indicates replaying what a brief would have produced over past days. However, the phrasing is oblique, and it never plainly states the verb (rehearse/preview) or distinguishes itself from siblings like morning, my_brief, or save_brief beyond the closing 'nothing is saved'.

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 explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The phrase 'nothing is saved' hints at a dry-run contrast with save_brief/set_brief, but the agent must infer that rather than being told.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description's main contribution is the optimistic-concurrency guard: "Refused when the record changed since its `confirm`." That is a genuinely useful precondition beyond the structured fields, but the side effects on success are described only in opaque imagery ("lanes drawing their own edition"), leaving the agent unsure what the write actually produces.

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?

At two sentences it is short and front-loads the action, but the wording is ornamental rather than economical — "its lanes drawing their own edition from the next morning" occupies a full clause without conveying actionable information. Brevity here trades away precision rather than 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?

An output schema exists, so return values need not be explained, and the schema fully documents both parameters. What is missing is breadth: the description never places the tool relative to its many brief-related siblings or states plainly what the save commits the agent to, leaving enough ambiguity that the definition is only minimally sufficient.

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%: both `brief` (format, schema/example locations, name resolution) and `confirm` (token from set_brief or amend_brief) are fully documented in the schema itself. The description adds essentially no parameter-level meaning beyond restating the confirm dependency, 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 brief kept, on the reader's yes" gestures at persisting a brief conditioned on a confirmation, but the actual verb (save) exists only in the name and title, not the prose. The second half ("its lanes drawing their own edition from the next morning") is metaphorical enough that an agent cannot be sure whether this merely stores the record or also triggers downstream generation, and nothing distinguishes it from siblings like set_brief or amend_brief.

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 explicit when-to-use statement and no mention of the obvious alternatives (set_brief, amend_brief) that also deal with briefs. The only routable hint is the refusal condition tied to `confirm`, which tells the agent a prior token is needed but not when to prefer this tool over its siblings.

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 the most consequential behavior: a draft without `preview` is a dry run that returns what the draft would yield over a day, the matched pieces, and a `confirm` digest — a preview/commit two-phase flow that no annotation implies. 'The same move again changes nothing' reinforces idempotentHint=true. It stops short of stating permissions or error conditions, but this is substantive added context.

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 compact — three sentences — but not front-loaded: the opening clause is figurative rather than declarative, and the middle sentence chains four ideas ('a day, the pieces it finds, and a `confirm` digest') in a way that slows parsing. Nothing is redundant, but the wording costs more than it earns in places.

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 needn't be described, and the preview/commit mechanics are covered. Still, for a 7-parameter tool where two parameters and most of the `draft` structure are undocumented in prose, an agent gets an incomplete picture of valid inputs and of what happens when neither target nor draft fits.

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?

At 43% schema coverage the description carries weight, and it does explain `target` forms, the amplitude ladder (away/low/normal/high) as 'a step', and the `preview` digest as the confirm token. However `note` and `language` go unmentioned and the `draft` sub-fields are left entirely to the schema, so the compensation is only partial.

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 does convey two distinct operations — moving an existing 'magnet' via target+amplitude, and saving a draft definition — but it does so in heavily metaphorical prose ('Move one of the reader's magnets, what draws their own edition'). The plain verb+resource ('save an interest/magnet to the reader's profile') is never stated, so the agent must decode the metaphor before it can confirm the tool's job.

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 real branch logic: use the target+amplitude path for a named subject, and the draft path 'For a subject no target names'. It also spells out the preview-then-confirm sequence. But it never differentiates from siblings like my_interests or why, and gives no prerequisites or when-not-to-use 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?

The annotations already declare idempotentHint=true, destructiveHint=false and, notably, readOnlyHint=false; the description earns credit for explaining that flag by disclosing the cost model: one credit per search, balance returned, and the same search on the same day is paid only once. That is real context annotations cannot carry. It says nothing about rate limits, failure modes, or what happens when the query exceeds the five-name OR limit, which keeps it below the top of the scale.

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 is front-loaded, but the first sentence is a long run-on enumerating every output column, much of which duplicates the output schema rather than earning its place. The credit/caching sentence is the highest-value line and would benefit from being surfaced earlier and separately from the row-format inventory.

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, the description need not spell out return values, and it covers the non-obvious parts: cost and same-day deduplication, sort order (today's list, then score, then newest), and the handoff to `why` and `save_interest`. Remaining gaps are minor, such as empty-result behavior or errors from an over-long OR query.

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 `days`, `limit` and the query grammar (OR, five names max, whole words, `*` suffix wildcard), making 3 the baseline. The description restates `days` scoping and the query semantics but adds no meaning beyond those field descriptions; the wildcard and OR-limit rules are verbatim schema content.

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 the specific resource and scope: stories from the last `days` whose pieces name the query, one row per story. It also names two downstream siblings (`why` for a row's `item_id`, `save_interest` for examples), which helps an agent place it in the workflow. It stops short of contrasting with other retrieval siblings such as `top` or `morning`, so differentiation is only partial.

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 rather than stated: you search when you need stories matching a named query, and a returned row's `item_id` routes to `why` while its title feeds a draft via `save_interest`. Those are useful explicit next-step pointers, but there is no when-not-to-use guidance and no comparison against the other read tools in the sibling list.

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, while the description adds useful operational context: the feed is refreshed hourly, results are ranked, scores reflect the edition's perspective, and a note appears when few outlets from a country are read. Some terms remain opaque, but the added behavioral detail is meaningful beyond 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 front-loaded with what the tool returns, but it is a single dense sentence with cryptic phrases such as 'mains pulled by the edition's stakes' and 'the honest pair.' It also mentions parameters not in the schema, which adds confusion rather than useful structure.

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 usefully sketches the return shape and country-filter behavior. However, for a three-parameter tool with low schema coverage, it leaves `limit` and `edition` semantics unclear and is weakened by references to absent `as_of` and `window_hours` parameters.

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 only 33%, so the description must carry more parameter meaning. It explains the `country` filter and gestures at `edition`, but does not explain `limit` or the default edition behavior, and it references `as_of` and `window_hours`, which are not present in the input 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 resource and scope: 'stories of the last 24 hours in rank order,' including returned fields like rank, title, score, mains, outlets, and story page. It is distinguishable as a ranked top-stories feed, though it does not explicitly contrast itself with siblings such as `morning` or `search`.

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 'last 24 hours in rank order' and the optional `country` filter behavior, but there is no explicit guidance on when to use this versus `morning`, `search`, or the brief-related tools. The description does not state exclusions or 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar here is lower. The description adds real value by enumerating exactly what evidence is returned (score arithmetic, gates, carriers, neighbors, exclusions), which matters because there is no output schema. It says nothing, however, about failure modes — e.g. what happens if item_id is unranked or the date/edition yields no story.

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 whole definition is a single ~70-word run-on sentence with a nested parenthetical, no front-loaded summary, and no separation of purpose from return contents. Every clause carries information, so there is little pure filler, but the lack of structure makes it hard to parse quickly.

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 spends its budget describing the return payload, which is the right call for a diagnostic explainer. Against that, a 3-parameter tool at 0% schema coverage gets no parameter documentation and no usage context, so an agent can know what comes back but not confidently how to call 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 description coverage is 0%, so the description carries the full burden for item_id, date and edition, and it largely fails: 'a piece' only obliquely implies item_id, and 'at the edition's home and at the world' hints at the edition parameter/default without stating allowed values, while date is never addressed at all. The heavy return-value detail does not compensate for undocumented 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 conveys that this explains why a piece sits where it does on the list — its rank, score and the factors behind them — so the general intent is inferable. But the purpose is delivered as an unlabeled inventory of return contents ('mains', 'pulls', 'stakes', 'gates') rather than a stated verb+resource, and several terms are undefined domain jargon. It also makes no attempt to distinguish itself from siblings like top or search, which an agent would plausibly confuse it with.

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 prerequisites, and no naming of alternatives. An agent gets no signal about whether to call this after search/top, or what makes a piece eligible to be explained. Usage must be entirely inferred from the sibling list.

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