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

Annotations already declare readOnly=true, destructive=false, openWorld=false, so safety is covered. The description still adds genuinely new behavior: the per-call cap ('at most limit spans'), the distinction between pageTotal (matched volume) and returned items, and the pagination continuation mechanism. One gap: it calls the continuation value 'nextCursor' while the input parameter is named 'cursor', which could momentarily confuse the agent.

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?

Four short sentences, front-loaded with the verb and resource, then return-shape, then pagination, then the sibling relationship. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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?

An output schema exists, so return values need not be described, and the description still adds the two facts an agent most needs (page size cap and continuation). It is nearly complete for a read-only search tool, with only the undocumented time-range and context parameters left implicit.

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 33%: only q and context_id are documented in the schema, while from, to, limit, cursor are bare. The description partially compensates by explaining limit's effect and the cursor continuation, but it says nothing about the from/to time-range defaults (now-1h/now) or the ctx_* context parameter's precedence. Baseline 3 for a description that adds some but not full parameter meaning.

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 and resource ('Search APM spans/traces') and pins the backend ('Spans API v2'), which separates it from the log-oriented siblings like dd_logs_search and dd_events_search. It also clarifies the relationship to dd_log_get, so an agent can place this tool in the right workflow slot without opening the schema.

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?

Gives concrete usage directions: use nextCursor to page, and pair with dd_log_get after finding a trace_id in logs. That is real workflow guidance rather than an implied purpose. It stops short of explicit when-not-to-use exclusions (e.g. use dd_metrics_query instead for aggregate metrics), so it is not a 5.

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