fow_revise_srs_baseline

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value on top: it is an append ('appends a baseline revision') that retains immutable history and approval requirements, warns that authority/evidence 'may require reconciliation', and states 'Does not silently accept drift' — behavior an agent would not otherwise know.

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?

Front-loaded with the core action in sentence one, then layered Prerequisites/Effects before the help escape hatch. Slight redundancy ('classifying changes' appears in both the opening and the Effects block), and the verbose fow_capabilities call line costs space, but nothing is truly wasted.

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 destructive, open-world mutation this covers prerequisites, effects, history/approval retention, and reconciliation risk, and an output schema exists so return values need not be described. The only gap is the absence of any explicit pointer to how it differs from fow_import_srs or fow_revise_requirement, which matters given the dense sibling set.

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 documents all seven parameters thoroughly, and this is the baseline of 3. The description reinforces a few of them (previous_baseline_id, changed source, governed approval) but adds no syntax, format, or constraint detail beyond what the fields already spell out.

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 (apply/revise) and resource (the current SRS baseline), and the qualifier 'source-proven' cleanly separates it from a raw import. It does not, however, name the nearest siblings (fow_import_srs for first-time import, fow_revise_requirement for single requirements), so the agent must infer the boundary from the resource noun alone.

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?

'Single operation; call directly without an operation argument' plus an explicit Prerequisites clause (exact current previous_baseline_id, changed local source, required governed approval) tell the agent when the tool is callable and what must be true first. It stops short of naming an alternative or a when-not condition, so it is clear context without exclusions.

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