podyx_v1_reports_addons

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them by specifying the auth scopes required, that evidence rechecks all resource permissions, the exact failure contracts (422 with no partial headline for typed input/complexity/allocation coverage, opaque 404 for invalid or inaccessible references, 429 analysis_busy with Retry-After: 1, native 500/503 for infrastructure), and that callers must follow all pagination. This is exactly the failure-mode and side-effect detail an agent needs and that structured fields cannot express.

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?

Purpose is front-loaded and most sentences carry operational weight (auth, error contracts, pagination), but the middle is a dense run-on of HTTP status codes that could be a compact list. The closing clause 'a quote does not reserve a slot or lock a price' reads as boilerplate borrowed from quote tools and does not belong in a read-only report definition.

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 read-only, zero-required-parameter report endpoint the description covers auth, failure semantics, idempotency, and pagination obligations well. Since there is no output schema, it should ideally say more about what a 'headline' contains and how comparison_to_date/comparison_from_date alter the response, which is the remaining gap.

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?

The description itself adds almost nothing about parameters, but the nested schema documents each inner property (page, basis, metric, preset, plan_id, dates, group_by, page_size, inactivity_days, comparison bounds) thoroughly, so the schema is carrying the load. The one real gap is that the top-level 'query' wrapper has no description anywhere, and the description never clarifies that filters nest inside it or that client_id is the 'signed client filter' that triggers the clients:read requirement.

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 specific verb and resource ('Analyze studio addons') and pins it to GET /api/v1/reports/addons, which separates it from the sibling report endpoints (capacity, customers, metrics, packages, revenue, summary) and from the plain add-on list/CRUD tools. It stops short of saying what the analysis actually produces (headline metrics, comparison basis), so it is clear but not fully self-describing.

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?

There is no explicit when-to-use guidance and no named alternative: nothing tells the agent whether to reach for this report versus podyx_v1_list_addons or podyx_v1_reports_metrics for a given question. The permission prerequisites ('reports:read', 'clients:read') and 'Read/preview only' are eligibility constraints, not usage routing.

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