blacklist.add

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

There are no annotations, so the description carries full responsibility for disclosing behavior. It only states that a rule is added and maps kind values to meanings; it does not mention duplicate handling, immediate effect, side effects, or permissions for this mutating operation.

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?

One compact sentence front-loads the action and then efficiently lists the parameter vocabulary. No filler or redundant restatement.

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?

Core invocation is sufficiently specified: the required kind choices are defined, value semantics are mostly inferable, and an output schema exists so return values need not be documented. The main gap is behavioral context such as duplicate rules or activation timing, but for a simple mutating tool this is acceptable.

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?

With 0% schema coverage, the description compensates well by defining the four accepted kind values and their meanings, and by clarifying that price_drop expects a cumulative percentage threshold. It does not describe the optional note parameter or the value format for the other kinds, but the mapping is a significant addition.

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 the specific action '添加屏蔽规则' (add blacklist rule) and enumerates the rule kinds, making its purpose clear. It is easily distinguishable from siblings like blacklist.remove, blacklist.list, and blacklist.test.

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 action itself implies the tool is for adding blacklist rules, but no explicit when-to-use guidance or exclusions are given. An agent must infer from the sibling names that removal, listing, and testing are separate tools.

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