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

The annotations already declare that this is a non-readonly, non-idempotent, open-world write, but the description adds real behavioral context: the nightly check backfills the baseline from 28 days of history and records met/partial/missed. It also notes that the tool warns when a line already passes today, that failure lines are separate lines, and that manual-kind lines require a verdict by hand. It still does not say what a call returns (line id, warnings) or what happens on a duplicate line.

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 content is information-dense with little padding, but it is delivered as one long comma-and-semicolon-chained paragraph that is hard to scan. The enumeration of metric and rule behaviors would be far more usable as short bulleted clauses. Length is defensible for a 12-parameter nested tool, but the structure is not.

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 12-parameter tool with a nested schema and no output schema, the description covers the full lifecycle: creation, nightly evaluation, baseline sourcing, and the manual verdict path. Gaps remain around return values, duplicate handling, and permission/connection requirements, but nothing essential to a correct call 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 the baseline is 3, but the description adds non-obvious interactions that the schema only hints at: a rule with op <=/>= plus on_miss forms its own failure line even on the same number, and every_days turns a line into a recurring check. It also clarifies that omitting path makes a search measure the site's best page. It leaves baseline vs. baseline_note interplay mostly to 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 names a concrete verb and resource ("adds a line" to "the client's expectations ledger") and explains what a line contains: a change, the number it should move, an expectation, and a deadline. It separates itself from automatic ledger entries for page and Google Ads changes and from expectation_verdict for manual verdicts. The only weakness is that the first sentence defines the ledger rather than the action, so the verb arrives slightly late.

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?

It says when to call it ("the moment you make it") and when not to (page changes and Google Ads changes add lines automatically), and it routes manual lines to expectation_verdict. It also gives selection guidance for metric kinds (gsc_page vs gsc_query with path) and for recurring checks (rule every_days). It lacks explicit prerequisites, such as whether the client must already exist or be connected.

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