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

Beyond the annotations, it discloses that the tool only affects the caller's own account, does not change object data, and creates a new entry on every call even for the same URL. The duplicate-creation warning directly reinforces the non-idempotent behavior declared in 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?

The main purpose and constraints are front-loaded, and the removal route is kept short. It is slightly verbose because the duplicate warning is restated across two sentences and the English keyword tag is appended, but no sentence is seriously off-topic.

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 two-parameter favorite-add tool with no output schema, the description gives the necessary scope, mutation boundary, duplicate risk, pre-check guidance, and removal alternative. The minor reference to a saved filter is not enough to make the definition incomplete.

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 explains both url and title. The description adds useful parameter-relevant meaning by clarifying that repeated use of the same URL is not treated as the same favorite and can produce duplicates.

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 verb and resource: adding an object to the user's own favorites. It also explicitly distinguishes the action from object mutation and from removal, so an agent can tell what it does 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?

It says to use the tool for frequently used objects, warns to check onto_favorite_index first to avoid duplicates, and names onto_favorite_delete for removal. These are explicit when-to-use and alternative-routing instructions.

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