Rate a cooked recipe

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

Annotations already establish this is a non-read-only, non-destructive write, so the description's added value is the state-transition side effect: the week becomes 'done' once all selected recipes have feedback. This is genuinely useful. However, it does not disclose whether re-rating overwrites existing feedback, whether partial ratings are allowed, or what happens if feedback already exists for the recipe.

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 with zero filler. The first sentence front-loads the core action and scope; the second delivers the consequential side effect. Every word earns its place and the structure is easy to parse quickly.

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

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

An output schema exists, so return values are covered elsewhere. The description covers the primary action and the weekly completion side effect, which is the key non-obvious behavior. The gaps are edge behaviors an agent would reasonably need: re-rating/overwrite semantics, whether the recipe must be in the current week's selection, and failure conditions when prerequisites aren't met.

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?

With 0% schema description coverage, the description carries the burden of parameter meaning. It partially compensates: '1-5' clarifies the rating scale (though the schema already encodes min/max), 'comment' confirms the optional string field, and 'for a member' maps to member_name. But recipe_id is left entirely unelaborated, and the relationship between rating and an existing prior rating is 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 opens with a specific verb ('Record') and a clearly scoped object ('post-cook feedback (1-5 + comment) for a member'). The 'post-cook' qualifier meaningfully distinguishes it from sibling tools like add_ballot_feedback, add_vote, or favorite_recipe. It doesn't explicitly name a sibling, which keeps it just shy 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?

The intended context is implied: feedback is recorded after cooking, and the weekly completion rule ('when every selected recipe of that week has feedback the week becomes done') gives a trigger condition. However, there are no explicit when-not-to-use statements, no named alternatives among 30+ siblings, and no prerequisites such as whether the recipe must belong to the currently selected week.

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