The Observatory

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations don't: the return is Markdown, and each story carries two addresses (Observatory site and source). Since there is no output schema, this return-format disclosure matters.

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

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

One sentence, front-loaded with the resource and scope, and every clause (format, story addresses) carries information an agent needs. The phrasing 'each of its stories' addresses on the Observatory's site and at the source' is slightly heavy but not wasteful.

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 tool with annotations covering safety, the description supplies the one thing structured data lacks: the shape of the returned content. Error behavior for an invalid or nonexistent id is unaddressed, but nothing critical to invoking 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 coverage is 100% with a single well-documented id parameter, so baseline is 3. The description adds no syntax, format, or range detail beyond what the schema already provides.

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

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

States a specific resource (one issue) and its scope ('in full'), plus the output format (Markdown). This clearly distinguishes it from latest_issues (a list) and search_news (a search), though it never explicitly says the verb 'retrieve by id'.

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

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

No when-to-use guidance, no statement of prerequisites, and no naming of alternatives. The routing hint ('as latest_issues and search_news give it') lives in the parameter schema, not the description, so an agent gets no help choosing this tool over its siblings from the description alone.

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

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

Annotations already declare readOnlyHint and closed-world behavior, so safety is covered. The description adds useful behavioral context beyond annotations: ordering ('newest first') and the returned fields. It does not cover pagination or default-limit 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?

A single front-loaded sentence: source, ordering, then return fields. Every element earns its place with no 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 simple read-only list with fully described parameters and no output schema, the description supplies the return shape and ordering. It is complete enough to call correctly, though it omits usage steering and pagination 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?

Schema description coverage is 100%, so both group and limit are fully documented in the schema. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States the resource (The Observatory's latest issues), ordering (newest first), and return fields. It reads as a list tool rather than a single-issue tool, but does not explicitly name or contrast with siblings like get_issue or search_news.

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

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

No when-to-use guidance, no alternatives named, and no exclusions. An agent must infer that this is for browsing recent issues rather than searching or fetching a specific issue.

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 openWorldHint=false, covering the safety profile. The description adds some return-content context (publications, coverage, days, hour, feeds, subscription address), but omits pagination, ordering, or format details.

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

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

A single sentence with the resource front-loaded and no filler. It is slightly dense and reads more like a content blurb than an instruction, but nothing is wasted.

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

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

For a no-parameter listing tool with annotations carrying the safety profile and no output schema, the description adequately conveys what comes back. It could be stronger on ordering/pagination, but nothing an agent needs to call it 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a no-parameter tool 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 resource – publications grouped by product group – and enumerates what each entry covers (coverage, days, hour, feeds). The verb is implied by the name rather than stated, and it never distinguishes this listing from siblings like latest_issues.

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 and no reference to the sibling tools (get_issue, latest_issues, search_book, search_news). An agent has no signal about when this full listing is preferable to the narrower search or latest variants.

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

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

Annotations already establish this is a safe read (readOnlyHint=true) over a closed corpus (openWorldHint=false), so the bar is lower. Beyond that the description adds real behavior: results come back 'best first' (ranked) and enumerate the returned fields including the credibility label when a check was performed. It omits pagination behavior and the default result count (only in the schema), so it stops 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?

Front-loaded with the corpus definition, then the return shape — a sensible order with no filler sentences. It is dense, with one long embedded clause about the notes, but every clause carries information rather than restating the name or title.

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 usefully enumerates the returned fields (headline, summary, type, tags, desk, source, address, date, credibility label), which is exactly what the agent needs to judge relevance. The remaining gap is that query syntax is delegated to a sibling rather than described, so a reader must consult search_news for the format.

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 all four parameters (desk, limit, query, since) are documented in the schema with enums, defaults, and formats. The description's only parameter-relevant contribution is deferring query syntax to search_news, which adds no concrete syntax detail. Baseline 3 applies when the schema carries the load.

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 Book: every note the Observatory's desks have written since late September 2026') plus the scope that defines the corpus, including it being unpublished notes that never reached an issue. That corpus definition implicitly separates it from the published-issue tools (get_issue, latest_issues, search_news), so an agent can tell which set of content this searches without opening the schema.

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

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

The only routing hint is 'Same query syntax as search_news,' which signals the two tools are parallel corpora but never states when to pick this one over search_news or get_issue. Usage is left to inference from the corpus description rather than an explicit when-to-use rule or exclusion.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description still adds real behavioral context: result ordering ('best first'), the corpus boundary (last year of daily and weekly issues), and the shape of each result. With no output schema, this return-shape disclosure is doing useful work.

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 scope and return shape, with no padding. The final syntax clause is slightly garbled ('or.') but does not meaningfully impede use.

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

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

No output schema exists, and the description compensates by naming the returned fields and ordering, plus the corpus time window. The enum-backed `group` values and `limit` default are left to the schema, which documents them adequately.

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 would be 3; the description earns above that by documenting the query grammar (words, quoted phrases, -word negation), which the schema only describes as 'what to look for'. The `since` bound is also implied by the 'last year' corpus statement.

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 stories in the Observatory's published issues') plus the coverage window (daily/weekly, last year), which is enough to separate it from search_book and latest_issues by resource. It never names a sibling explicitly, so the differentiation is implicit rather than stated.

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 scope ('published issues, last year') implies when the tool applies, and the query-syntax note gives invocation guidance. There is no explicit when-to-use/when-not or pointer to an alternative tool such as search_book for non-issue content.

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