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

The description warns that 'Any untracked data or schema changes will be lost,' which indicates a destructive operation, yet the annotations declare destructiveHint=false. This is a direct contradiction. According to the rules, a score of 1 is required when the description contradicts annotations. The description itself provides useful safety information, but the conflict with the structured annotation undermines trust.

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 is composed of two terse, effective sentences. The first states the core operation and its consequence, the second adds bulk support. No unnecessary words or repetition. It is front-loaded with the most critical 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?

The description covers the basic operation and warns about data loss, but it fails to explain what 'reset' means precisely (e.g., does it roll back to a specific migration version? Does it remove all migration history?). It also ignores migration_version and provides no information about return values or side effects beyond the warning. Given the destructive nature and the annotation contradiction, more detail is needed for safe use.

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. It clarifies branch_id (development branch) and branch_ids (bulk support), but migration_version is entirely unmentioned. The meaning of migration_version is left unclear, and the description adds only partial value over the raw 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?

The description clearly states the action: 'Resets migrations of a development branch.' This is a specific verb-resource pair that distinguishes it from sibling tools like supabase_rebase_branch or supabase_delete_branch. The scope is limited to development branches, adding clarity.

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 description implies usage for development branches and mentions bulk execution, but it does not explicitly state when to use this tool versus alternatives (e.g., rebase, merge, or delete). It lacks clear preconditions or exclusions, so it provides minimal guidance beyond the basic context.

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