compare_assets

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

With no annotations, the description carries full burden. It reveals that the tool composes inspect_asset bridge-side on both paths and excludes the path field from comparison. This is sufficient disclosure for a read-only diff operation, though it omits details about permissions or side effects, which are minimal for a comparison tool.

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 three sentences, each earning its place: first sentence states the core function, second gives use cases, third notes an important exclusion (path field). No redundant or vague language. Information is front-loaded effectively.

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?

While the description covers purpose, usage, and parameter semantics, it lacks detail on the output format. The tool returns 'fields that differ' but does not describe structure (e.g., key-value pairs, nested vs flat). Given no output schema, this gap could leave the agent unsure how to consume the result. However, for a diff of inspect_asset outputs, the return format is implied by the input schema's field structure, so it is marginally adequate.

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% with descriptions for all three parameters (path_a, path_b, fields). The description adds value beyond the schema by explaining that the path field is excluded from comparison and providing guidance on using the fields parameter to scope the diff to a specific subset. This clarifies behavior not captured in the schema.

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 clearly states the tool performs a symmetric diff between two assets by comparing their inspect_asset outputs. It uses specific verb+resource ('diff' + 'assets') and distinguishes itself from siblings like inspect_asset by explaining it composes two inspect_asset calls and returns only differing fields.

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 description provides clear use cases: checking what changed between versions of a blueprint or cross-checking duplicated assets. It implies when to use (for symmetric diff) and excludes path field, but does not explicitly state when not to use or list alternatives, though the sibling set includes inspect_asset which could be an alternative for single asset inspection.

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