blackbox

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

The annotations declare readOnlyHint=false, and the description partially explains why by noting a report may be written when 'export' is supplied, which is a small useful addition. However, it never states what is otherwise mutated, what permissions are needed, or what the default non-export behavior does, leaving the non-read-only nature largely unexplained.

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?

At two short sentences it is tight and front-loaded, but the opening phrase is dense jargon of unclear value, and the second sentence is the only operationally useful part. It is brief without being informative.

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 three-parameter tool with no output schema and only 33% schema coverage, the description should compensate by explaining the inventory concept, the trace/root_spec behavior, and the return/artifact shape. Instead it leaves the core workflow opaque, so an agent lacks what it needs to invoke this correctly.

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 only 33%: 'export' is documented in the schema and the description adds that it triggers writing a JSON report. But 'trace' and 'root_spec' (both string with defaults) receive no explanation in either the schema or the description, so meaning is missing for two of three parameters.

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 is a noun phrase ('Deterministic, outside-in Black-Box Contract inventory') rather than a clear verb+resource, so an agent cannot confidently tell what action is performed or what artifact is produced. It also does nothing to distinguish this tool from siblings like inspect, validate, trace_create, or capabilities.

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 statement of when to use this tool versus the many siblings, nor any prerequisites or exclusions. The only conditional mentioned ('May write a report if export is given') describes a side effect, not selection guidance.

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