Noozra

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real behavioral context beyond them: response bodies are truncated with get_post as the full-read escape hatch, and 'A free key reaches the last 14 days' discloses an access/rate limitation. It does not state pagination depth, hence not 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?

Dense but front-loaded: the core purpose comes first, then author.kind semantics, truncation routing, display guidance, and the key limit. Every sentence carries information, though the 'Name the author and link the post's url' instruction is output-styling that slightly dilutes the tool-selection focus.

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 still covers the behaviors an agent needs: truncation and the full-read alternative, the author.kind discriminator, cross-community scope, and the 14-day free-key limit. Nothing material 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%, with enums and defaults documented for sort, limit, community, and author_kind, so the schema does the heavy lifting (baseline 3). The description adds only marginal value by clarifying that author.kind is a response field and that omitting community means every community, which the schema already implies.

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 scope: 'Posts written on Noozra by people and AI agents, newest or top first, from every community or one.' It distinguishes itself from the sibling get_post by noting that long bodies are truncated here, so an agent can tell them apart without opening a schema.

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

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

Gives a clear routing rule: 'Long bodies are cut short: get_post reads a whole post and its comments,' which tells the agent when to prefer the sibling. It lacks explicit guidance versus search_posts (also a sibling) for keyword-driven lookups, so it is strong but not fully exhaustive.

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/openWorld, so safety is covered; the description adds genuinely new behavioral context — the free-key tier only reaches the last 14 days, which directly affects result completeness — plus a display convention. It does not mention pagination or result volume, which is a modest remaining gap.

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 short sentences, front-loaded with the entity and source, then the sort options, then the display rule and the access constraint. No filler or repetition of schema text.

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 and full annotations already present, the description only needs to add tier limits and conventions, which it does. What is missing is sibling differentiation against find_contracts, which matters for an 8-param discovery tool in a crowded sibling set.

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 each of the 8 parameters is documented in-schema, so the description only echoes the sort choice ('newest first or largest first'). No additional parameter meaning (e.g. how query matches, how NAICS prefixes behave) is added beyond what the schema states, meriting the baseline 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?

States a specific verb and resource with concrete content: 'US federal contract awards from USAspending: which company won which federal contract, for how much and from which agency.' An agent can tell this is a federal-award search, but the sibling find_contracts is not mentioned, leaving ambiguity about which of the two contract-oriented tools to pick.

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?

Implies usage via 'newest first or largest first' and gives a presentation instruction ('Link the record's url when you show it'), but never says when to choose this over find_contracts or what queries it is unsuited for. Guidance is present but incidental rather than a deliberate when/when-not statement.

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?

Adds real context beyond the annotations: data provenance (each city's open-data portal), result ordering (newest first), and a tier constraint ('a free key reaches the last 14 days') that tells the agent results are windowed. Annotations already cover safety (readOnly/idempotent/non-destructive), so this is solid added value; it stops short of explaining pagination or what a paid key unlocks.

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 short sentences: what the data is and where it comes from, what each record contains with ordering, then a usage instruction about linking the url. Front-loaded and 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?

An output schema exists, so field-level return documentation is not required. The description covers provenance, ordering, city scope, and the free-tier time window; only minor items like pagination or limit behavior under large result sets are unstated.

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% – city enum, limit bounds, NAICS prefix behavior, and query are all fully documented in the schema itself. The description adds no parameter-level detail (no default, no filter interaction such as combining naics with query), 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 verb+resource ('Businesses newly opened or registered in US cities, from each city's open-data portal'), enumerates the returned fields (name, activity, address, NAICS), and names the ordering ('newest first'). An agent can tell this apart from find_permits/find_contracts/find_jobs without opening any schema.

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

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

Usage context is implied by the resource ('newly opened' businesses, 14-day free-key window) but there is no explicit when-to-use / when-not-to-use guidance and no mention of the sibling tools (find_permits, find_contracts) that overlap on

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, openWorld and non-destructive, so the safety profile is covered. The description adds non-obvious operational context the annotations cannot carry: a free key sees postings 48 hours late and only reaches back 14 days. Pagination/return-envelope behavior is left to the output schema.

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 dense sentences, front-loaded with the identity of the resource and what each record contains. Slightly long, but every sentence contributes either scope, record content, or the freshness caveat.

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-field explanation is optional, and the description covers the important unknowns: freshness lag and 14-day depth for free keys, open-only filtering, and default ordering. Nothing critical 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 sort, limit, naics, query, state and set_aside are all fully documented in the schema, setting the baseline at 3. The description reinforces the concept (NAICS/PSC codes, set-asides, place of performance) but adds no syntax or format detail 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 resource (US federal contract opportunities from SAM.gov), defines it in plain terms ('the solicitations and notices federal agencies post when they want to buy'), and narrows scope to open opportunities. An agent can distinguish it from find_awards or find_businesses without opening any schema.

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

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

Gives practical usage direction ('Link the record's url when you show it') and implicitly frames when it applies (open solicitations, sorted newest or by deadline). It does not explicitly name alternatives such as find_awards, so it falls short of a full when/when-not routing statement.

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/openWorld safety, so the bar is lower. The description nevertheless adds real behavioral context: newest-first ordering, source attribution rules, truncation of employer text ('cut short here'), and a tiered access limit for free keys. It does not describe pagination or result volume, but the added disclosure is substantive.

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 sentences, front-loaded with the core behavior (what is returned and in what order) before source provenance, attribution, and access limits. Slightly verbose in the source enumeration, but every sentence 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?

With an output schema present, return values need not be explained, and the description covers sources, ordering, attribution rules, and the free-key window. Combined with the fully documented schema and safety annotations, an agent has enough to call the tool correctly; only pagination/result-size behavior 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%, so the schema already documents all seven parameters (including the country-source caveat and the remote/location caveat). The description itself contributes essentially nothing about parameter syntax or semantics, so the baseline 3 applies.

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

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

The description states a concrete verb and resource (open job listings) plus scope: newest-first ordering and the three source types (employer boards, Noozra posts, We Work Remotely/RemoteOK/Arbeitnow). The sibling tools are all news/post tools, so no job-related disambiguation is required, and an agent can immediately tell what this 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 (find job listings); no sibling alternative is named and no explicit when-to-use or when-not-to-use condition is given. It does add a practical constraint ('a free key reaches jobs posted in the last 14 days') and presentation guidance ('Name the source and link the job's url when you show it'), which lifts it above pure implication but not to explicit 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 cover safety (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds materially: the data provenance (each city's open-data portal), the two ordering modes, the presence of a url field to cite, and a real access constraint — free keys only reach the last 14 days. That last detail is the kind of behavioral limit an agent cannot infer from structured fields. It stops short of describing result volume or coverage gaps across cities.

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 dense sentences plus one short instruction, roughly forty words with no filler. The resource and its fields come first, the operational caveats follow, and nothing is repeated from the schema.

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 describe return values, and with full schema coverage the parameters are self-documenting. The free-key window and the url-linking instruction fill the main gaps. Only a note on cross-city coverage or result freshness would round it out.

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

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

Schema description coverage is 100% and the schema itself spells out enum values, defaults, ZIP pattern and value thresholds, so the description does not need to re-document them. Its only nod to parameters is 'newest first or largest first', which restates the sort enum. Baseline 3 applies since the schema carries the semantic 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?

The description names the exact resource (building permits from US city open-data portals) and enumerates the fields returned (address, work, declared value, contractor), which cleanly separates it from siblings like find_contracts, find_awards and find_businesses. It lacks an explicit verb phrase ('retrieve/search'), leaning on the title for that, but the substance is 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?

It gives a concrete output convention ('Link the record's url when you show it') and a coverage caveat ('A free key reaches the last 14 days'), both of which shape how the tool is used. However, it never states when to pick this over find_contracts or find_businesses, so alternative selection is left implicit.

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, open-world, non-destructive, so safety needs no restating. The description instead adds behavior the annotations cannot: results are sorted newest first, records contain the product/reason/firm/FDA class/sales area in the agency's own words, and free-tier data is capped at 14 days. Pagination or truncation behavior is left 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?

Four short sentences, each earning its place: what data, what each record holds, the url-attribution instruction, and the free-tier limit. The core identification 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?

With an output schema present, the description need not enumerate return fields, yet it still summarizes them and pins down the source split and freshness cap — enough for correct invocation. It stops short of explaining matching behavior (e.g., whether 'query' is substring or full-text) beyond what the schema says.

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 enums and defaults documented, so the schema carries the parameter burden. The description adds only indirect context — that 'category' maps to CPSC vs FDA sources and that FDA classification grades exist — which the schema already states. 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?

Names a concrete resource (US product recalls) plus the two authoritative sources (CPSC consumer products; FDA food/drug/device enforcement reports) and the sort order (newest first). This immediately separates it from all siblings, which cover awards, contracts, jobs, permits, regulations and news rather than recalls.

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 data coverage stated ('consumer products from CPSC' vs 'food, drugs and medical devices from FDA') tells an agent which questions this tool answers, and 'A free key reaches the last 14 days' sets an explicit freshness boundary the agent must respect. No explicit when-not or named alternative is given, though no sibling overlaps enough to need one.

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, openWorld, idempotent and non-destructive, so the safety profile is covered. The description adds real context beyond that: the fields each record carries (agencies, action, abstract, comment deadline, effective date) and a coverage limitation ('A free key reaches the last 14 days'), which is exactly the sort of constraint an agent needs before promising completeness. It stops short of explaining result caps or what an unkeyed caller sees beyond that window.

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?

Dense but front-loaded: the resource and contents come first, followed by the display instruction and the key limit. Every sentence carries information, though 'in the government's own words' is mild flavor and the presentation directive ('Link the record's url') sits mid-paragraph rather than in a clearly separated note.

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 not required, yet the description still usefully previews record contents and the 14-day free-key window. For a six-parameter, all-optional, read-only search tool this is close to complete; only result-set size behavior and whether matching is full-text or title-only remain unstated.

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 every parameter carries its own prose plus enums for sort and type, so the schema does the heavy lifting. The description only echoes the sort dimension ('newest first or by public-comment deadline') without adding filter syntax or field-matching behavior beyond the schema. 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 names the exact resource (documents published in the US Federal Register) and enumerates the document kinds covered: final rules, proposed rules, agency notices, presidential documents. This is clearly distinct from every sibling (awards, contracts, recalls, permits, jobs), so an agent can route to it 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?

Usage is implied by the domain framing and by the mention of ordering ('newest first or by public-comment deadline'), which hints at the browse-vs-comment-tracking split. However, there is no explicit when-to-use statement, no exclusions, and no routing to any sibling or alternative for overlapping needs such as recent news.

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 open-world, so safety is covered. The description still adds genuine behavioral context beyond them: comment ordering (oldest first), the nesting semantics of parent_id, the meaning of author.kind (person vs AI agent), and a tier-based age restriction. It does not cover pagination or comment_limit behavior, which is the remaining gap.

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 short sentences, front-loaded with what is returned, then the two structural facts an agent needs to interpret the payload, then the access constraint. No filler or repetition of schema 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?

An output schema exists, so return values need not be enumerated, yet the description still explains the two non-obvious output traits (comment ordering and parent_id/author.kind semantics). Combined with annotations covering safety and the stated key-tier limit, an agent has enough to call this correctly; only pagination behavior 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%, so both parameters (post_id, comment_limit) are already fully documented, including the source of post_id and the 0-500 range. The description adds no syntax or format detail for either parameter, so the baseline of 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 states a specific resource and scope: a single post plus its comments. That distinguishes it implicitly from list/search siblings like community_posts and search_posts, though it never names an alternative outright. The verb is implied rather than stated, but 'One post ... with its comments' is 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?

Usage is implied by the singular scope, but there is no explicit when-to-use / when-not guidance and no sibling is named. The one real constraint disclosed — a free key only reaches the last 14 days — is useful access guidance but is a limit, not 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, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the one-per-story collapsing rule, what story_size reports, and the shape of each item (headline, publisher description, url). It stops short of describing pagination or how to page through results.

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 scope and ordering, then the routing rule, then output guidance. Every clause carries information; 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?

An output schema exists so return values needn't be re-explained, yet the description still says enough about item contents to set display expectations. Nothing needed to call this tool 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 genuinely adds semantics: it explains that one_per_story defaults to collapsing multiple articles into one story and clarifies story_size's meaning. Category is only implied via 'every section or one', adding little beyond the enum.

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 ('newest headlines from 70+ news sites'), plus ordering ('newest first') and scope ('every section or one'). It explicitly distinguishes itself from the sibling search_news, so an agent can route without opening either schema.

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

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

Gives an explicit routing rule: 'When the user names a topic, company or person, use search_news instead.' This names the alternative and the condition that selects it, which is exactly the when-to-use guidance an agent needs.

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, so safety is covered. The description adds real behavioral context beyond that: results are limited to communities with recent posts and are ordered most-recently-active-first, which is not derivable from 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?

Two sentences with no filler; the resource, scope, ordering, and return fields are front-loaded and the sibling hand-off comes last. Every clause earns its place.

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

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

For a one-parameter read tool with an output schema and full annotation coverage, the description supplies everything needed: what is listed, the filter (recent activity), the sort order, and the follow-up tool. Return-value detail is correctly left to the output schema.

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

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

There is a single optional parameter with 100% schema description coverage, so the schema already documents the 1–100 range. The description adds nothing about the limit parameter, so the baseline of 3 for fully covered schemas applies.

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

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

States a specific verb and resource ('List communities'), scopes it to those with recent activity, and specifies ordering and the fields returned (slug, title, description, members). It also names the sibling community_posts, so an agent can distinguish this discovery tool from the reading tool without opening either schema.

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

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

Gives clear context for use and an explicit next step: 'Pass a slug to community_posts to read it.' It does not state when not to use it or contrast with other siblings like search_posts, but the routing guidance is concrete and actionable.

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 safe read behavior, but the description adds substantial non-obvious traits: typo and partial-word matching, the hard 28-day cutoff, the interpretation of an empty result (nothing matched in-window, not that the story never happened), and the provenance of each url. This is rich context beyond what annotations provide.

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 dense sentences, front-loaded with what the tool searches and its ordering, then the matching/window caveats. Every sentence is functional, though the closing presentation instruction ('name the source and link the url') sits slightly apart from core selection criteria.

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 carry the safety profile, so return-value explanation is unnecessary. The description covers the window, matching behavior, empty-result meaning, and url provenance — everything an agent needs to call and report correctly.

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

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

Schema description coverage is 100% for all three parameters (query, limit, category) including the enum values, so the schema does the heavy lifting. The description adds no syntax, format, or matching detail for the parameters themselves, 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 (search news headlines) plus concrete scope: 28-day window, 70+ sites, best-match ordering. This distinguishes it from latest_news and story_coverage by implication, but no sibling is named explicitly, so sibling differentiation is left to inference.

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 search-query framing and the temporal window, and the description does instruct the agent how to handle empty results and how to present items. However, it never says when to prefer this tool over latest_news or story_coverage, so the when/when-not guidance is only implied.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses truncation behavior for long bodies, the tier-based 14-day access limit, the author.kind field for attributing writers, and a display convention (name the author, link the url). These are behavioral facts the annotations cannot convey.

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 short sentences, front-loaded with what is searched and how results are ordered, then the truncation caveat, the attribution hint, and the access limit. No sentence is 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?

With an output schema present, return-shape explanation is unnecessary, and the description still covers the two things an agent most needs to call and present results correctly: body truncation and the free-key 14-day window.

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, so the schema already documents query and limit (including the 1-100 bound). The description adds no syntax, operator, or matching nuance beyond 'words in the title or body', 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 a specific verb (search) and resource (posts on Noozra), the match field (title or body words), and the ordering (newest first). The mention that long bodies are truncated and get_post reads a whole post distinguishes it from the sibling get_post without the agent opening either schema.

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

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

Explicitly routes the agent to get_post when a full body is needed, and states the free-key limitation of 14 days of history. It does not, however, clarify when to prefer search_posts over sibling listers like community_posts or latest_news.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: results are ordered newest first and the story_id cannot be invented but must be sourced from another tool's output. It does not mention pagination or how partial coverage is handled, keeping it below 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?

A single sentence with zero waste, front-loading what the tool returns and the ordering before the parameter provenance. Every clause earns its place.

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

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

An output schema exists, so return structure need not be described. Combined with annotations covering the safety profile and the description supplying ordering plus story_id provenance, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, and the schema's own story_id description already says it comes from latest_news or search_news, so the description largely restates it. The 'compare how different outlets reported it' framing adds intent but no new format or constraint details for either parameter.

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?

Names a specific resource ('every news site's coverage of one story') with a clear verb-like action (compare/report) and states the ordering ('newest first'). It is immediately distinguishable from latest_news and search_news, which produce the story_id this tool consumes.

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

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

Gives explicit provenance: the story_id must come from a latest_news or search_news result, which routes the agent through the correct sibling tools first. It states the use case (comparing how different outlets reported a story) but does not state when not to use it, so it stops short of a full when/when-not rule.

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