uds_inspect_level

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

With no annotations provided, the description correctly takes on the burden of behavioral disclosure. It explicitly declares the operation READ-ONLY and specifies the return shape as one MCP INSPECT_JSON line. It does not explain optional behavioral aspects like dry-run or editor-open interactions, but the core safety and output behavior are clear.

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 one dense, front-loaded sentence with no filler. The READ-ONLY label, target actors, and key fields all appear early, though the colloquialism 'that have actually burned us' adds color rather than technical precision.

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 read-only inspect tool with defaults on all optional parameters, the description is minimally sufficient: the caller knows what is inspected and what is returned. However, with no output schema and no explanation of dryRun, timeoutSeconds, or allowWithEditorOpen, non-default invocations lack needed context.

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%, so the description needed to compensate by explaining the parameters. It only gives context for 'map'; dryRun, timeoutSeconds, and allowWithEditorOpen are never mentioned, leaving their meaning and effects unexplained.

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 states a specific verb and resource: it reports the sky (UDS) and weather (UDW) actors in a map, and lists the exact fields inspected. This clearly distinguishes it from write-oriented siblings like uds_apply_preset and from generic probe tools.

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 READ-ONLY label and the phrase 'fields that have actually burned us' imply this is the diagnostic tool to run before modifying sky/weather state, but it does not explicitly state when to prefer it over alternatives such as unreal_probe_actor or uds_apply_preset. Usage context is implied rather than spelled out.

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