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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description must carry the real burden. It fails to disclose the critical behavior for a settings tool: whether unspecified fields are reset, preserved, or overwritten, whether the change is idempotent (an idempotency_key exists but is never explained), or what happens when both read and write semantics coexist. The 'no changes reads' fragment is the only behavioral nugget and it is barely parseable.

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?

It is a single short sentence with no padding, which is good, but the second clause ('no changes reads') is a compressed fragment that costs more in ambiguity than it saves in length. Brevity here reads as under-specification rather than efficiency.

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 10-parameter mutation tool with a nested object, three enums, an idempotency key and no output schema, one terse line is far from sufficient. An agent cannot confidently determine write semantics, defaults, or which parameters are meaningful without reading the raw JSON schema.

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?

There are 10 parameters with 0% schema description coverage, three of them enums (alert_sensitivity, applovin_coverage, innovation_cadence) and one nested object (digest_delivery), plus an undocumented idempotency_key. The description gestures at only 'cadence, alerts and digests' and says nothing about workspace, timezone, relevance_filter, applovin_coverage, max_tracked_ad_competitors, or creative_action_destinations, so it does not compensate for the schema gap at all.

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 names the resource (competitor-intel settings) and the domains touched (cadence, alerts, digests), and hints at a dual read/write mode. But it never says what the tool actually persists or how it differs from siblings like competitor_signals_update, workspace_settings_save, or competitors_save, so an agent must guess at boundaries.

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 clause 'no changes reads' cryptically implies that omitting change fields yields a read, but that is the only usage hint. There is no explicit when-to-use guidance, no statement of prerequisites or permissions, and no mention of the alternative read paths an agent might prefer.

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