List software inventory

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it retrieves software 'across the network' and lists the fields returned, which is useful scope context. However, it does not disclose behavioral traits like pagination behavior, potential large result sets, or any prerequisites. This is consistent with annotations, so it is not misleading, but it adds only modest context beyond the structured metadata.

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 a single sentence that starts with the action verb 'Retrieves' and conveys the scope, resource, and key fields without redundancy. Every phrase adds value, and it is appropriately front-loaded with the primary action. This is a model of concise, structured tool documentation.

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?

The tool is a read-only list operation with a comprehensive schema, strong annotations, and no output schema. The description adequately lists the return fields, which is important since no output schema exists. It does not explicitly mention pagination, but the schema's page/pageLimit parameters cover that. Given the tool's simplicity and the high schema coverage, the description is nearly complete, though it could have noted that results may be large or that filters are intended for narrowing.

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 100%, with all 7 parameters having detailed descriptions in the input schema. The tool description does not add any additional parameter meaning beyond what the schema already provides. Therefore, it receives the baseline score of 3 for parameter semantics, as the schema does the heavy lifting.

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 uses a specific verb ('Retrieves') and clearly identifies the resource ('all software detected across the network'). It lists key fields returned (version, manufacturer, category, installation counts, license copies, compliance status), which distinguishes it as a network-wide software inventory with compliance data. However, it does not explicitly differentiate from sibling tools like inventory_installed_software_list or inventory_license_software_list, so purpose clarity is strong but not maximally distinct.

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 usage context is implied by the description: use this tool when you need a network-wide software inventory with compliance status. There is no explicit guidance about when not to use it or which alternative tool to prefer (e.g., inventory_installed_software_list for per-computer details). The schema's filters suggest usage for narrowing results, but the description itself does not clarify when to use this vs siblings.

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