marketplace_webhooks_get_collection

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

No annotations are provided, so the description carries full behavioral burden, yet it discloses nothing about pagination defaults, response shape, required scopes, or what deprecation means operationally (removal date, error behavior). Only the deprecation label adds any behavioral signal.

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 very short, but the brevity is under-specification rather than conciseness. The parenthetical '(GET /v1/marketplaceWebhooks)' is pure redundancy with the preceding text, so the only content is a deprecation tag plus a repeated URL.

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 deprecated collection endpoint with no annotations and no output schema, the description should at minimum say what is returned or point to a replacement. It does neither, leaving an agent unable to judge whether this tool is safe or useful to call.

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% and both parameters (limit, fields_marketplaceWebhooks) have their own descriptions, so the schema does the work. The description adds no meaning beyond the schema, fitting the baseline 3.

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 gives only the HTTP path 'GET /v1/marketplaceWebhooks', which implies a list operation on marketplace webhooks, plus a [DEPRECATED] tag. It never states in words what the tool does or what marketplace webhooks are, and there is no differentiation from siblings like marketplace_webhooks_create_instance beyond the implicit GET-method mapping.

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 [DEPRECATED] prefix hints the tool should be avoided, but there is no explicit instruction about when to use it, when not to, or which non-deprecated tool replaces it (e.g., webhooks_get_collection or marketplace_webhooks_update_instance siblings). The agent is left to infer everything.

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