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

Annotations declare readOnlyHint=false and destructiveHint=true, and the description does not contradict them — it implies a mutating write operation. The description adds valuable context beyond annotations by disclosing the write-tier approval flow (manager approval, from-now-on vs just-once semantics), which annotations do not cover. However, it does not explain what is modified or side effects of adding a rule to an existing style guide, and with destructiveHint=true more behavioral disclosure would help.

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 compact with the primary purpose front-loaded in the first sentence, followed by a bracketed operational note about the approval tier. The bracketed section earns its place by conveying critical workflow behavior that the annotations and schema do not. Minor inefficiency: the usage triggers overlap conceptually with the style_rule examples, but overall it is tight and well-organized.

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 usage triggers and the approval workflow, and the schema fully documents all parameters. There is no output schema, so the description could clarify what the tool returns or confirms. For a mutation tool flagged destructiveHint=true, it could better describe what gets modified (the pipeline's style guide) and any irreversible consequences, leaving a modest 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?

Schema description coverage is 100%, so all four parameters are documented in the schema (pipeline_id, output_format, style_rule, companyId). The description adds modest value by giving example style_rule values ('Use bullet points for lists', 'Keep under 150 words') and concrete user-phrase triggers. Since the schema already carries full parameter documentation, the baseline of 3 is appropriate.

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 states a specific verb and resource: 'Manually add a style rule to a pipeline.' It gives concrete usage triggers (bullet points, hashtags, word count, tone) and the 'pipeline style guide' framing differentiates it from siblings like update_brand_guidelines and update_pipeline. Minor ambiguity: the name says 'update style guide' while the description says 'add a style rule to a pipeline,' which could confuse whether rules attach to a pipeline or to a style guide.

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?

Provides strong when-to-use context with explicit example triggers ('always use bullet points', 'never include hashtags', 'keep it under 100 words') and general content preferences. The bracketed note adds operational guidance ('Call it on the first clear ask; the card is the yes — do not re-ask in chat'). However, it does not name alternatives or state when NOT to use it, e.g., distinguishing brand-level style edits handled by update_brand_guidelines.

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