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

Annotations already establish this is a safe, closed-world read, so the bar is lower. The description still adds real behavioral content by disclosing what the response reveals – last-arrival timestamps and blocked reasons such as billing pause or missing credentials – which tells the agent what diagnostic outcomes to expect.

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?

Two compact sentences with zero padding: the diagnostic scope comes first, then the exact user question it serves. The question-form framing is unusual but front-loads the actionable signal efficiently.

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 explained, and the single optional enum parameter is trivial. The description covers intent, scope, and the diagnostic categories well; only the boundary against neighboring marketing/alerts/login tools is 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 description coverage is 0%, but there is only one optional parameter whose enum values are self-explanatory. The description adds the useful fact that the filter is optional ('Optionally filter by channel') and treats it as a narrowing filter rather than a required selector; it adds nothing about default behavior when omitted, which the schema also leaves silent.

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 resource (marketplace connections) and a specific set of questions it answers: per-channel health, last data arrival time, and stale/blocked states. That is well beyond restating the name, though it never explicitly names a sibling it is distinct from (e.g. get_marketplace_login_issues or get_marketplace_alerts), so an agent must infer the boundary.

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 gives an explicit trigger scenario in the user's own words ('my Flipkart/Myntra/Amazon data is not updating'), which is exactly the kind of routing signal an agent needs. It stops short of stating when NOT to use it or which sibling covers adjacent cases like login issues or alerts.

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