direct_set_keyword_bids

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

With no annotations, the description carries the burden of disclosing write behavior. It explicitly marks the operation as 'WRITE' and notes that allow_write=true is required, which gives some safety context. However, it does not explain that existing bids will be overwritten, whether changes are reversible, or how dry_run interacts with allow_write. This is minimal but not completely absent.

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 entire description is a single, front-loaded sentence that packs the operation type, target resource, currency, API method, required fields, and a key precondition. There is zero fluff; every word 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 write tool with no output schema and only partial schema coverage, the description is incomplete. It omits important context like the effect of dry_run, the role of the project parameter, the exact bid array format, and potential side effects. While it does flag WRITE and allow_write, it leaves significant gaps that could lead to misuse.

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 only 50% (project and allow_write have descriptions; bids and dry_run do not). The description adds little beyond the schema: 'keyword_ids required' is already encoded in the schema's required fields, and 'allow_write=true' is present in the schema description. It does not clarify the structure of the bids parameter or the purpose of dry_run, which are undocumented in the schema.

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 clearly states the verb 'set', the resource 'keyword search bids', and the currency (₽), which distinguishes it from sibling tools that set bid modifiers or keyword states. It also names the underlying API method keywordbids.set, leaving no ambiguity about what the tool does.

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 'WRITE:' prefix and 'keyword search bids' phrasing imply the tool is for setting keyword bid amounts, but no explicit exclusions or alternative tools are mentioned. For example, it does not contrast with direct_set_bidmodifiers or direct_set_keyword_states, so an agent must infer when this tool is appropriate versus alternatives.

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