get_annual_nominees

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

Annotations declare read-only/idempotent/non-destructive/open-world, and the description adds substantial context beyond them: a 1 req/s hydration throttle, default 10 / max 20 per call, the hydrate=false fallback (cached entries plus id stubs), and the constraint that media URLs are reference-only and never downloaded. That is exactly the kind of rate-limit and side-effect disclosure the annotations don't carry.

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, with purpose and pagination/throttle facts front-loaded before the navigation hint and legal caveat. No clause is redundant with the schema or with the annotations.

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?

Four parameters, no output schema, but the description covers throughput, page-size bounds, the cached/stub degradation path, what a hydrated record contains, and usage restrictions. An agent has everything needed to size calls and chain into get_site_details.

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 adds real meaning: it explains the cost model behind hydrate (1 request/second) and describes what hydration returns (site summaries carrying siteSlug and inLocalIndex). Limit/offset semantics are 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+resource+scope: 'List nominees in one official Awwwards Annual Awards category'. It distinguishes itself from bulk/detail siblings by tying itself to a single category and by pointing at get_site_details for follow-up, though it never explicitly contrasts with get_annual_nominee (the single-nominee sibling).

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 operational context: category slug comes from get_annual_categories, and an agent should jump to get_site_details when the daily index contains the site. It also states the licensing boundary (personal, non-commercial inspiration only). What's missing is an explicit when-not/alternative statement, e.g. when to prefer get_annual_nominee or a non-hydrating call.

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