set_version

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

Annotations only flag it as a non-read-only, non-destructive, closed-world write. The description adds real value by disclosing that two separate files (manifest and AssemblyInfo/csproj) are modified in a coupled way and why the coupling matters. It omits the dry_run preview option and how the update_assembly/update_manifest toggles change behavior.

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?

Two sentences, action stated first, rationale second, with zero filler. Every clause earns its place.

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?

An output schema exists, so return values need not be explained, and the core multi-file write behavior is covered. However, with no parameter descriptions anywhere, the meaning of project, version format, and dry_run remains undocumented for a five-parameter mutation tool.

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% across five parameters, so the description must carry the load. It partially compensates by identifying the two version targets (which map to update_manifest and update_assembly) but says nothing about the project parameter, accepted version format, or what dry_run does.

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 and two concrete resources: it sets the manifest version and the AssemblyInfo/csproj version together. That makes it clearly distinct from read-only siblings like read_manifest, get_assembly_info, and compare_versions, though it does not name an alternative explicitly.

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?

'Use this for version bumps' gives an explicit usage context, reinforced by the concrete failure mode (Release builds fail when manifest and assembly versions differ). It stops short of when-not guidance or pointing to compare_versions for checking divergence first.

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