The Moorish Times

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds the useful behavioral fact that output is aligned block by block with both URLs, but says nothing about what happens when only one edition exists or when the id is ambiguous across languages.

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 short sentences, zero redundancy, with the concrete output shape front-loaded ahead of the audience note. Nothing here is padding.

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 needn't explain return values, and it correctly focuses on scope and audience. A one-param read-only tool is well served, though the single-edition or missing-translation edge case is unaddressed.

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 single id parameter already documents both the piece-id forms and the URL alternative. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific resource and operation: both editions of one piece, aligned block by block, with both URLs. An agent can tell it returns a paired bilingual view rather than a single document, which separates it from fetch. It does not name the sibling alternative explicitly, keeping it just short of 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?

"For readers comparing the languages or checking a translation" implies the usage context but never states when not to use it or which sibling to use instead (fetch, search). The selection signal is thematic rather than operational, leaving the agent to infer the routing rule.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: the front-matter fields included, the French fallback when no English edition exists, and that the fallback is signaled in the output. It doesn't cover failure modes for an invalid id.

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 tight sentences, each carrying distinct information, with the primary payload (full text plus front matter) front-loaded and mode differences second. No filler or restatement of the 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 annotations and an output schema present, the description covers the modes, locale fallback, and content shape well. The remaining gap is procedural: no hint that ids typically come from search results, nor what happens on an unknown or malformed id.

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%, and the description compensates for the undocumented gap: the 'format' enum has no schema description, yet the description explains what summary and outline yield versus full. It also reinforces the French fallback tied to 'locale'. It adds no detail on accepted id forms beyond what the schema already states.

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 ('The full text of one article or news brief') plus the exact rendering (Markdown with front matter and references). It clearly reads one piece rather than listing or searching, though it never names a sibling such as search or related to route the agent explicitly.

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 usable selection guidance among the tool's own modes — 'format summary gives the front matter and summary only; outline gives the section headings' — so an agent knows when to pick a lighter format. It stops short of saying when to use this tool instead of siblings like search, related, or series.

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, idempotentHint=true and openWorldHint=false, so safety and repeatability are covered. The description adds the useful detail that output includes both extracted reference data and a pre-formatted citation, but says nothing about permissions, failure modes, or what happens with a URL input versus an id.

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 front-loaded sentence listing the returned data first and the citation capability second, with no filler. Every clause carries 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-value explanation is optional, and the description still summarizes the payload shape. The only shortfall is the absence of any hint about how id versus URL inputs behave or what happens when a page has no sources.

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%: id is well documented and locale has its fallback rule spelled out, while style only has enum values. The description adds the meaning of the style parameter (APA/MLA/Chicago citation format) beyond the bare enum, but contributes nothing about default behavior or id formats, so it is a modest supplement rather than a compensation.

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 the exact resource (references, outbound links, image credits) and adds the citation-generation capability with named styles, so it is far from a tautology. It does not explicitly contrast itself with siblings such as fetch or related, but the resource is distinct enough that an agent can tell what it returns.

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 only implied by the content listing: use it when you need a piece's references or a formatted citation. There is no statement of when to use it versus fetch/related, and no exclusions or prerequisites 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 establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail about sort order and bilingual naming, but it does not mention pagination, result limits, or whether all tags are returned.

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 compact sentences with the core result description front-loaded and no filler. The second sentence carries directly relevant bilingual filtering context.

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 list tool with an output schema and annotation coverage, the description is mostly complete: it explains ordering, counts, and edition naming. Minor gaps remain around min_count semantics and pagination or limits.

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 most parameters are documented already. The description clarifies locale naming and that either language is accepted for tag filters, but it does not explain min_count or add much beyond the schema for prefix and category.

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?

Describes a specific resource (tags) and what the result contains: counts per tag, most-used-first ordering, and edition-specific naming. It is clear enough to distinguish from most siblings, though it does not explicitly contrast with search or related tag tools.

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?

Provides no explicit when-to-use or when-not-to-use guidance, and does not name alternatives such as search or related. The note about both names being accepted in tag filters is useful naming behavior, but it is not tool-selection 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 read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds the ranking rule ('closest first') and the matching criteria (tags + section), which is genuinely useful, but says nothing about behavior for unknown ids, empty results, or per-locale matching.

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 short sentence with zero padding, and the matching basis and ordering come early. It loses a point only because the fragment form reads as a caption rather than a self-contained instruction.

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. What remains missing is routing guidance against the many sibling discovery tools and any hint about the 'limit' parameter, making it 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 67%: 'id' and 'locale' are documented, but 'limit' has only type/default/max with no prose anywhere. The description mentions no parameters at all, so it does nothing to close the remaining gap or clarify what 'closeness' means for results.

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 fragment 'Pieces that share tags and section with a given piece, the closest first' does convey the retrieval concept and its similarity basis, but it is a noun phrase with no verb and no differentiation from siblings like 'search' or 'series' that could also surface related content.

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 statement of when to pick this over 'search', 'series', or 'list_tags', and no prerequisites (e.g. that the id must already exist or came from 'fetch'). The agent must infer usage entirely from the name.

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=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds genuinely new context: it records the task only and never personal data, which tells the agent what is transmitted and the privacy constraint. It stops short of saying who receives it or whether submission is anonymous.

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

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

Two sentences, zero waste, with the action front-loaded and the privacy guarantee second. Nothing redundant or padded.

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

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

An output schema exists, so return values need not be explained. Purpose, trigger, and data-handling are covered. The only meaningful gap is routing versus send_to_newsroom, which would make the definition fully self-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 description coverage is 100%, so both parameters (task, description) are already documented with examples and constraints in the schema. The description adds no field-level meaning beyond that, so 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+resource: reporting a task a reader wanted but the server, site, or API could not do. It is clearly a feedback/gap-report tool, not a data fetch. It doesn't explicitly contrast with the closest sibling send_to_newsroom, so an agent must infer the boundary.

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 the trigger condition (a task could not be done), which is reasonably clear context. But there is no explicit when-not-to-use and no named alternative, even though send_to_newsroom exists and could plausibly be confused with this.

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/idempotent/non-destructive, and the description still adds real behavior: accent-insensitive matching, semantic fallback ordering, empty-query ordering, and cursor-based pagination via 'next'. The only weak spot is that it advertises a 'match: semantic' parameter that is not in the input schema, which could send the agent looking for a knob that does not exist.

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?

Four front-loaded sentences: capability, matching strategy, empty-query edge case, return shape. Dense with no filler. The parenthetical 'match: semantic' is the one sentence fragment that costs clarity rather than buying it.

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 11 optional parameters and an output schema, this covers what the agent needs: what is searchable, how matching degrades, what an empty query does, and how to page. The dangling 'match' reference is the only gap, and since the output schema carries the return contract, describing results here is a minor redundancy rather than a flaw.

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?

Adds meaning beyond the 73%-covered schema: bilingual/accent-insensitive search, 'every tag must be present' semantics, and date-range phrasing. Against that, the 'match: semantic' reference maps to no declared parameter, and cursor/limit/sort behavior is left entirely to the 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?

Opens with a specific verb and resource ('Search every article and news brief') and enumerates the facets it searches, so the agent knows this is the corpus-wide discovery entry point rather than a by-id lookup. It never names a sibling such as fetch or related, 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?

Gives concrete invocation guidance: an empty query returns the newest pieces, and semantic matching is the fallback 'when keywords find few'. That tells the agent both the zero-result escape hatch and the degradation path, but it does not say when to prefer this over fetch, related, or timeline.

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 openWorldHint=true and idempotentHint=false; the description adds genuinely non-obvious context: the send is an external submission requiring user consent, and unauthenticated sends are throttled per network. It does not warn that repeated calls create duplicate tips or describe what happens to the message downstream, which is the remaining gap for a non-idempotent external write.

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 tight sentences: the action and its scope come first, then parameter intent, then the auth/rate-limit caveat. No sentence repeats the name or the schema, and nothing is buried.

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 consent plus auth scope cover the compliance burden. What's missing is the cross-field rule that a correction should name the page and what the user experiences after a send, which an external non-idempotent write would benefit from.

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 80%, so the baseline is 3; the description goes beyond it by defining message as the user's own words (not a paraphrase) and reply_to as the address to use only if a reply is wanted. The language parameter is undocumented in both schema and prose, though its fr/en enum is self-explanatory.

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 destination (send the newsroom a message) and enumerates the exact message kinds the tool carries, so the action is unambiguous. It does not distinguish itself from the nearby sibling report_missing, which an agent could plausibly mistake for the right tool when the user is flagging a mistake in a piece.

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 real routing conditions: send only on the user's behalf and with their consent, and include reply_to only when they want an answer. Auth context (Bearer token, scope newsroom:send, per-network limit without one) further tells the agent what to expect. It stops short of naming exclusions or pointing to an alternative tool.

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

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

Annotations already declare a safe, read-only, idempotent, closed-world read, so the description doesn't need to restate safety. It adds real value beyond them: the return shape in each mode (counts + latest piece vs. every piece) and the ordering guarantee ('reading order, oldest first').

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 of definition followed by the two conditional modes in a tight semicolon structure. Front-loaded with the concept, no repetition of schema or annotation content.

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?

Output schema exists, so return-value detail needn't be spelled out, and the description still covers both invocation modes and ordering. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes beyond the schema by explaining the semantic consequence of omitting slug (aggregate listing) and of providing it (full article sequence), which is the key thing an agent must understand before calling.

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 ('running stories the desk follows as one series') with concrete examples (2026 elections, Sahara), and its two operating modes. This is clearly distinguishable from siblings like search, fetch, or list_tags.

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 what happens with and without a slug, which effectively tells the agent which mode to pick for listing vs. reading a series. It stops short of naming alternatives (e.g., 'use search to discover a slug you don't know'), so it's clear context but not full 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=true, idempotentHint=true, openWorldHint=false and non-destructive, so the safety profile is fully covered. The description adds that results include counts and URLs, a useful hint about shape, but says nothing about response size, locale-dependent content differences, or whether it is expensive to 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?

One compact sentence listing the payload contents with no filler. It is front-loaded with the scope ('what the magazine covers'), though the missing verb makes it read as a fragment rather than an instruction.

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 and annotations cover the safety profile, so the remaining burden is small. Still, for a zero-required-parameter, locale-sensitive aggregate tool the description should say when to reach for it over list_tags/series, which it does not.

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% and the single locale parameter is documented in the schema with enum values and a 'fr (primary)' note, so the baseline of 3 applies. The description never mentions that the map is edition-specific, so it adds no meaning beyond the 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 enumerates exactly what the map contains (sections with counts and URLs, top tags, featured pieces, author pages, series), which effectively defines the tool as a site-wide index rather than a search or fetch. It lacks an explicit verb and never names a sibling, but an agent can tell it is an aggregate overview tool.

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 statement of when to call this instead of alternatives, despite strong overlap with siblings like list_tags, series, and fetch, which surface the same content. The agent must infer that site_map is the 'get everything at once' entry point.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral detail beyond that — ascending date ordering and that first/latest mentions are marked — but says nothing about pagination, result volume, or how the filters combine, which matters for a 6-parameter tool.

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 tight sentences, with the core scope and ordering front-loaded before the secondary detail about marking first and latest mentions. Nothing is padded or redundant.

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

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

With an output schema present, return values need no explanation, and the annotations cover the safety profile, so the remaining burden is small. The only real gap is filter combination semantics for the six optional parameters, which is a modest but real omission.

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%, and the description only loosely gestures at parameters: 'tag or topic' hints that tag and query are alternative targeting modes, and 'date order' hints at since/until. It never clarifies whether tag and query can be combined, nor covers type or locale, leaving the most consequential ambiguity (all 6 parameters optional) unaddressed.

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 the resource (every piece on a tag or topic) and the shaping (date order, oldest first), which is more than a restatement of the name 'timeline'. It does not explicitly differentiate itself from siblings like search or series, which also retrieve related content, so an agent still has to infer the boundary.

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 phrase 'to follow how a story unfolded' implies a use case — chronological browsing of a topic over time — but there is no explicit when-to-use versus search, related, or series, and no statement of when this tool is the wrong choice. Usage is inferable but not spelled out.

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 that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond that: it returns pieces grouped by section with featured pieces first, and scopes content to Morocco via The Moorish Times. It still omits pagination or result-size limits, but the added organization and source context are meaningful.

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 front-loaded sentence with no redundant or filler content. Every clause contributes to purpose or scope.

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?

The tool has an output schema and annotations that cover return structure and safety behavior, so the description does not need to explain those. However, with five optional parameters and a sizeable sibling set, it leaves notable gaps: the 'tag' and 'locale' parameters are not addressed, and there is no guidance on when this digest is preferable to 'search', 'timeline', or 'series'.

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 60%; the description reinforces the meaning of 'since' (today/week/month) and 'category' (grouped by section) and implies sorting via 'featured pieces first.' It does not explain the 'tag', 'locale', or 'featured_only' parameters beyond what the schema already states, so it adds only partial meaning over the structured fields.

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 a specific resource and action: a digest of recent pieces from The Moorish Times, grouped by section with featured items first. It distinguishes itself from generic search by emphasizing recency and editorial digest ordering, though it does not explicitly contrast with siblings like search or timeline.

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 through phrases like 'what happened ... today, this week or this month' and 'digest,' suggesting this tool is for a recent-news overview. However, it gives no explicit when-to-use guidance or alternatives to choose from among the many sibling tools.

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