update_pipeline_stage

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the important sentinel semantics for expected_days and default_probability ('pass -1 to leave unchanged') and the range for default_probability. However, it does not clarify whether name and description, which have default empty strings, are overwritten when omitted, nor does it mention return values or error behavior, leaving significant gaps for a mutation tool.

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 extremely concise, consisting of a single-sentence purpose followed by a structured argument list. Every sentence and line earns its place, with no filler or redundant information. The use of a code-block list enhances readability and scannability.

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?

Given the tool has six parameters and no annotations, the description covers the basic purpose and parameter semantics but lacks important contextual details. It does not explain the update semantics for optional fields (e.g., whether name and description are always applied, or whether omitted fields are left unchanged), nor does it mention any return value or error conditions. While the presence of an output schema reduces the need to describe return values, the ambiguity around partial updates and potential overwriting of name/description is a meaningful completeness gap.

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?

The description lists all six parameters with brief functional explanations, compensating for the 0% schema description coverage. It adds meaning beyond the property names by explaining the pipeline_id and stage_id identifiers, and crucially clarifying the sentinel logic for expected_days and default_probability. While not deeply detailed, it gives an agent enough to understand what each parameter represents and how special values behave.

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 begins with 'Update an existing pipeline stage,' which is a specific verb+resource that clearly states the tool's function. It distinguishes itself from sibling tools like create_pipeline_stage and archive_pipeline_stage by focusing on updating an existing stage, leaving no ambiguity about its purpose.

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 updating existing pipeline stages but provides no explicit guidance on when to prefer this tool over alternatives like create_pipeline_stage or archive_pipeline_stage. There is no mention of prerequisites, such as the stage existing, or exclusions, so it offers only implied usage context.

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