Read PMDG CDU Screen

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe read operation. The description adds the prerequisite (EnableCDUBroadcast.N=1) and the return format (text rows + optional grid), which are not in annotations. No contradiction with annotations.

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?

Two sentences with no filler. The primary function is front-loaded in the first sentence, and the second sentence covers returns and a critical prerequisite. Extremely efficient.

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 operation with full schema coverage and an output schema, the description covers the essential context: what the tool does, which aircraft variants are supported, the return format, and a required configuration. Missing details like exact output structure are covered by the output schema. Overall, complete enough for an agent to select and call the tool 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?

The input schema provides 100% coverage with detailed descriptions for both parameters (cdu with per-variant mapping, variant with auto-detect). The tool description does not add any parameter-specific information beyond what the schema already contains. Since schema coverage is complete, the description adds no extra semantics, so a baseline of 3 is appropriate.

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?

Clearly states the verb 'read' and the resource 'PMDG CDU screen', and differentiates from siblings like msfs_get_pmdg_var by specifying it's for the CDU screen. Also provides variant-specific context (777 vs 737) which prevents confusion.

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?

Provides a clear context: reading the CDU screen. It mentions the number of CDUs per variant, which helps an agent know which unit to request. However, it does not explicitly name alternative tools or state when not to use it (e.g., when reading raw variables). The prerequisite (EnableCDUBroadcast.N=1) is a form of guidance. Overall, the context is sufficient but lacks explicit exclusion criteria.

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