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

Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=true), so the burden on the description is lower. The description adds useful behavioral context beyond annotations: validation requires a matching stored alert, force bypasses this, and the rule syncs to the phone for autonomous alert reading. It does not explicitly disclose overwrite behavior, but the destructiveHint annotation partially covers that.

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, each earning its place: the first states the core action, the second gives the key validation behavior, and the third explains the sync side-effect. No filler or repetition, and the most identifying information is front-loaded.

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 output schema exists, so the description need not explain return values. The presence of a nested rule object is substantial, but the schema covers its fields. The description adds the essential runtime behavior around alert matching, force, and phone sync. It misses only explicit guidance about overwriting existing rules and how this relates to test_parse_rule, which keeps it from a 5.

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 for the top-level parameters is 0%, so the description must compensate. It adds meaning to the force parameter by explaining it bypasses the stored-alert match requirement. However, it does little to explain the rule object's structure; that burden falls on the nested schema, which does contain rich descriptions. This is adequate but not fully compensating.

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 opens with a specific verb and object: "Save a parse rule for your account," which clearly identifies the action, resource, and scope. The follow-up about matching a stored alert or passing force=true further distinguishes this from sibling tools like list_parse_rules, test_parse_rule, and delete_parse_rule.

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 states an important acceptance condition: the rule must match a stored alert with the right amount, or force=true must be passed. This implies when the tool can be used, but it never explicitly explains when to choose this over test_parse_rule or delete_parse_rule, so the guidance is implied rather than stated.

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