qa_flyway_migration

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

With no annotations, the description carries the full burden and does add real value: it enumerates the failure classes it auto-repairs (duplicate versions, checksum mismatches, placeholder errors, missing-table failures) and hedges with "where possible." However, it omits that migrations mutate schema state irreversibly, whether a rollback exists, what happens when repair fails, and any auth/environment requirements.

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?

Three sentences, front-loaded with the action and environment before the trigger phrase and the repair details. Nothing is padded, though the trigger-phrase sentence is somewhat low-value relative to the repair list that follows it.

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 an unannotated mutating tool with no output schema, the description covers what it does and which failures it self-heals, but says nothing about return values, success/failure reporting, or the state left behind on partial failure. An agent can select it but cannot predict the outcome.

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% and there is only one optional parameter, so the schema already documents that omitting projects runs all discovered projects. The description's "for all configured projects" merely echoes that default rather than adding format or naming guidance.

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?

States a specific verb pair (run flyway repair and migrate) against a specific environment (QA) and a specific scope (all configured projects). This cleanly distinguishes it from siblings dev_flyway_migration and list_flyway_projects without needing to open any 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?

Gives a narrow invocation trigger ("Use when the user says 'QA Flyway Migration'") and implies the QA environment context, but never states when to prefer dev_flyway_migration or when not to run this, nor any prerequisites such as credentials or a clean working tree. Usage is implied rather than contrasted against alternatives.

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