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

Annotations only declare the write/read profile (readOnlyHint=false, destructiveHint=false), so the description carries the meaningful load and does so well: kind/tool_type/object_type are immutable after creation, config is validated against the kind's own validator and refused if the engine could not execute it, names must be unique per tool/object/kind, and crucially it clarifies this creates configuration only — no run, nothing written to the CRM.

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-loads purpose, then immutability constraints, then the shape-first workflow, then the inline segment example — a sensible priority order. It is dense and lengthy, with mild redundancy against the schema (both point to get_default_rule_config), but nearly every sentence 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?

For a 6-parameter, nested-config, no-output-schema mutation tool, the description covers everything needed to call it correctly: immutability of the discriminator fields, validation-on-create behavior, the one shape with no shipped default, uniqueness requirements, and the side-effect scope. Nothing material is missing.

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 coverage is 100%, so each parameter already has a description; the baseline would be 3. The description goes beyond that by spelling out the full JSON shape of a segment config (membership_mode, segments, predicate, nodes) and by clarifying object_type must be "any" for segments, which is genuine added meaning for a nested-object parameter the schema punts on.

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 (Create) plus resource (rule configuration on this connection) and enumerates the four concrete artifacts it can author: deduplication scheme, normalize scheme, segment definition, enrichment field mapping. An agent can immediately tell this apart from run-creating siblings like create_deduplication_run or create_segmentation_run.

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?

Explicitly instructs the agent to read the shape first via get_default_rule_config or get_rule_template, and gives a clear when-not with the alternative named: verification rules are seeded per connection and changed with update_rule_template, not created here. Nothing is left to inference.

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