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

Beyond the readOnlyHint annotation, the description reveals meaningful behavior: unknown slug returns 404, `advisory_list` is null when no advisory feed exists versus [] when upstream has published nothing, and advisories are returned newest first. This is substantial behavioral detail the schema and annotations do not provide.

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 description is dense but well-organized: first sentence states scope, second defines the engine parameter and error behavior, third details the advisory_list return contract. Minor extras like the issue reference and 'Market tier' add context but could be trimmed without losing essential information.

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?

Since there is no output schema, the description carries the full burden of explaining the return value. It lists the returned row fields, the advisory fields, ordering, null/[] semantics, and error behavior. For a read-only getter with two documented parameters, nothing critical is missing.

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 schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the `engine` slug semantics, linking it to the list output, and specifying the 404 failure mode. The `days` parameter gets no extra elaboration, but the schema already covers its range and default.

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 opens with a specific verb and resource: 'Get one software product (Market)', then identifies the resource as a catalogue engine slug. It enumerates the returned content (product metadata, host counts, compliance signal, advisory list), which clearly distinguishes it from list-style siblings like list_software.

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 clearly frames this as a single-engine lookup and gives a precondition: `engine` must be a catalogue slug 'as published in `engine` on the list', with an unknown slug resulting in 404. It does not explicitly name alternatives or when-not-to-use conditions, but the single-row scope is clear enough to route an agent correctly.

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