remove_favorite

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

No annotations exist, so the description carries the full behavioral burden. It implies mutation of user favorites but says nothing about authentication requirements (the endpoint shows a users/{id} path but not that it must be the logged-in user), idempotency, or behavior when the favorite does not exist. The keyword dump adds no behavioral content.

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 opens with a redundant restatement of the title, repeats itself ('Delete favorite' / 'Removes a recipe from the user's favorites'), embeds a raw HTTP route, and closes with a long keyword-stuffing list. Front-loading is present but roughly half the text is noise.

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 mutation tool with no annotations, no output schema, and two undocumented parameters, the description should at minimum state permission requirements and failure behavior. Instead it adds only keyword spam, leaving real gaps for an agent deciding how to invoke it.

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 0%, so the description must compensate. The bracketed endpoint [DELETE /api/users/{id}/favorites/{slug}] does clarify that 'id' is the user identifier and 'slug' identifies the recipe, which the bare uuid4/string schema does not convey. However, it adds no format or validation detail beyond that mapping.

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 sentence 'Removes a recipe from the user's favorites' gives a specific verb (removes) and resource (recipe from favorites), clearly distinguishing it from sibling add_favorite and the read-only get_favorites. The signal is buried under boilerplate ('Users: Ratings. Delete favorite.') and the raw endpoint, but the core purpose is unmistakable.

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 mention of the inverse add_favorite, no prerequisites or conditions. The agent must infer usage entirely from the name and the siblings list.

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