netlify-observability-services-reader

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

Annotations already declare read-only, idempotent, open-world and non-destructive, so the description's 'read-only' tag adds nothing. The one genuine addition is the multi-account rule (only the owning account answers; other accounts appear under notFoundIn). That is useful beyond the annotations, but it is duplicated five times with identical wording, so it adds no per-operation nuance.

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 same multi-account sentence is copy-pasted for all five operations, which is pure redundancy rather than differentiated content. The operation list sits on one run-on line with no formatting, and the repeated block buries the only useful information after three paragraphs of duplication.

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 complex five-operation tool the description does list the operations and the account semantics, and the nested schema supplies the parameter detail. However it never explains what each operation returns or how the operations relate (counts vs ranking vs time series vs raw logs), which is the main thing an agent needs when there is no output 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?

Top-level schema coverage is 50%, but the nested selectSchema is exhaustively documented (timestamps, filters, enums, sorting, pagination defaults). The description restates the account behavior that the account property already describes, and adds nothing about the operation-specific params. Baseline 3 is appropriate given the schema carries the detail.

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 ('select and run') plus the exact operation set (get-counts, get-topk, get-timeseries, get-request-logs, get-request-detail) and flags read-only scope, so an agent knows it is the Netlify traffic/log analytics facade. It does not distinguish itself from the other *-services-reader siblings (deploy, team, project), but the operation list makes the resource domain inferable.

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 'select one of' the operations but gives no criterion for choosing between get-counts, get-topk and get-timeseries, nor any when-to-use-this-vs-deploy-services-reader guidance. The only usage-adjacent content is which operations accept lists/'all' for accounts, and that is repeated verbatim rather than expanded.

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