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

Beyond the readOnly/idempotent annotations, the description discloses subtle behavior: the two-stage auto-detection (client-data-area probe vs title_pattern match), what a successful detection means, and that a fallback cross-catalog panel lookup is 'a guess, not a detection.' This is exactly the kind of non-obvious behavior an agent needs to trust the result.

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 dense but organized: a one-sentence summary, a bulleted list of levels, then a focused explanation of auto-detection edge cases. Every sentence contributes behavioral or usage information; there is no filler.

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 tool with no required parameters and rich schema/output schema, the description covers the full decision space: all three narrowing levels, auto-detection success/failure, and the reliability caveat on fallback matches. Nothing an agent needs to call it correctly is missing.

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%, so the baseline is 3, but the description adds real meaning for the two key parameters: catalog and panel define the three browse levels, and the auto-detection semantics explain what omitting catalog does. It doesn't add detail for limit/offset/response_format, but the schema already covers those.

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 opens with a specific verb and resource, 'Browse the aircraft L-var catalogs,' then defines three concrete output levels (all catalogs, panels in a catalog, variables on a panel). This distinguishes it from sibling tools like msfs_list_lvars or msfs_search_lvars, which operate on L:vars directly rather than the catalog hierarchy.

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?

It gives explicit usage context: no catalog lists catalogs, catalog only lists panels, catalog+panel lists variables, and it explains auto-detection and fallback behavior. It falls short of a 5 because it never explicitly names alternative tools or states when not to use this tool.

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

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

Beyond the annotations, the description discloses an important side effect: it automatically attempts to load the MobiFlight WASM extension for L-var support. It also clarifies the ordering requirement. It does not describe failure behavior or the effect of calling it when already connected, but the idempotentHint annotation covers re-invocation safety.

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 two short sentences with no filler. The primary action is front-loaded, and the prerequisite and automatic WASM behavior each earn their place. This is concise without losing necessary guidance.

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 zero-parameter connection tool with an output schema and informative annotations, the description provides the essential invocation context: it must precede all other tools and it automatically handles WASM loading. No additional parameter or return-value detail is needed.

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 tool has zero parameters and a fully covered schema, so there is no parameter information that the description needs to add. The baseline of 4 applies because the invocation surface is fully described by the empty 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 uses a specific verb and resource, 'Establish SimConnect connection to MSFS,' which clearly identifies the operation. It is further differentiated from siblings like msfs_disconnect and msfs_get_connection_status by its explicit connect action and the stated prerequisite that it must be called before any other tool.

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 explicitly states when to use it: 'Must be called before using any other tools.' This gives clear context for invocation. It does not explicitly name alternatives or exclusion cases, but siblings such as msfs_disconnect are obvious, and the strong prerequisite guidance is sufficient.

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

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

The description adds substantial behavior beyond annotations: silent ignore when the title matches nothing, no reply/error, null object_id meaning 'not confirmed to exist' rather than definite failure, and the separate causes for null. It also explains that object_id is the handle needed for SimConnect_AIRemoveObject. This is exactly the kind of non-obvious behavior an agent needs.

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 front-loaded with a one-sentence purpose, then a compact use-case statement, and then a focused edge-case explanation. The longer section about null object_id is justified because misinterpreting it would lead an agent to report a false failure.

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?

Given an output schema exists, the description does not need to redefine return values, yet it explains the meaning of object_id and message, clarifies the not-installed case, and gives removal context. For a spawn tool with non-obvious failure modes, this is complete.

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 schema already documents all 7 parameters (100% coverage), so the baseline is 3. The description adds meaningful parameter-specific context for 'title' by emphasizing that it must match an installed aircraft exactly and linking the resulting object_id to removal. Other parameters need no further explanation.

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?

States a precise action ('Spawn an AI aircraft or object at a position') and a clear resource. The 'AI' qualifier distinguishes it from actions on the user aircraft (e.g., msfs_set_aircraft_position) and from loading flights or events, so an agent can tell it apart from siblings.

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?

Gives an explicit use case ('building traffic or collision-avoidance test scenarios') and a hard prerequisite: the title must exactly match an installed aircraft. It does not name alternatives or when-not-to-use, but the context is clear and the tool's role is unique among the listed siblings.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, which implies a mutating but safe operation. The description adds no extra context like 'subsequent connection-dependent tools will fail until reconnected' or 'this aborts ongoing operations.' While not contradicting annotations, it fails to disclose the operational impact of closing the connection beyond the literal action.

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?

A single, precise sentence with no filler. The action is front-loaded and immediately clear. Every word earns its place; nothing is redundant or confusing.

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 no-parameter, single-action tool, the description is mostly sufficient. It lacks an explicit statement about side effects (e.g., affecting other tools) or return behavior, but the output schema exists and annotations cover safety. Given the simplicity, the gap is minor and a 4 is appropriate.

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?

With zero parameters, the schema trivially covers everything. The description adds no parameter details because none exist. Baseline of 4 applies per guidelines—the tool is inherently simple and no additional parameter explanation is needed.

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 ('Close') and a precise resource ('the SimConnect connection to MSFS'). It clearly distinguishes itself from siblings like msfs_connect (the counterpart) and status tools. The agent knows exactly what action this performs.

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 context is clear: this is the disconnect counterpart to msfs_connect. Though it doesn't explicitly list when to use it vs alternatives, the pairing with msfs_connect and the absence of any other disconnect tool make the usage obvious. Minor gap: no guidance on prerequisites (e.g., must be connected first).

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

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

Annotations already mark this as destructive and non-read-only, and the description complements them by disclosing that it can read or write any variable type, execute arbitrary code, and that the auto mode has a known misclassification heuristic. This adds meaningful behavioral context beyond the annotations without contradicting them.

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?

Every sentence in the description earns its place: purpose, capability, prerequisite, and a critical mode-selection caveat. It is front-loaded with the core action and remains focused despite covering an important edge case.

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?

Combined with the rich input schema, annotations, and an output schema, the description provides everything an agent needs: what the tool does, the required extension, the arbitrary read/write capability, and precise guidance for the mode parameter. No critical operational detail is missing.

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% and both parameters are already well documented with examples. The description adds extra semantic value by explaining the failure mode of mode='auto' and giving a concrete recommendation to pass mode='read' explicitly for expressions like '(L:A) (L:B) max'.

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 ('Execute'), a clearly defined resource ('RPN calculator code in the simulator'), and distinguishes this tool as a general-purpose bridge that can read or write any variable type. This differentiates it from narrower siblings like msfs_get_simvar or msfs_set_lvar.

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 gives clear context: it runs arbitrary RPN code, requires the MobiFlight WASM extension, and explicitly warns when to override the auto mode with mode='read' for compound read expressions. It does not name specific alternative tools, but the usage context is strong enough for an agent to choose it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that all variables across chosen sections are read in a single batched call, which is useful context, but it doesn't disclose other traits like potential response size limits or rate implications. The added value over annotations is moderate.

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 two short paragraphs, front-loaded with the core purpose followed by usage guidance. Every sentence earns its place: the purpose is stated, then examples, then the batched-call note. No fluff or redundancy.

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 snapshot tool with an output schema (indicated by has output schema: true), the description covers how to invoke it and why one might narrow sections. It lacks details about the response structure, but that is presumably covered by the output schema, so this is a minor gap. The description is sufficient for safe and effective use.

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 schema description already fully documents the 'sections' parameter (100% coverage), including valid section names and the default of all. The description adds practical, concrete use cases via examples, going beyond the schema by showing how to apply the parameter for specific scenarios, which enhances understanding.

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 reads a snapshot of the current aircraft state, with a specific verb and resource. It is distinct from siblings like get_simvar because it covers multiple sections, but it does not explicitly name any alternative tools, so differentiation relies on the reader's understanding of the tool landscape.

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 gives practical usage examples (e.g., sections=['position'] for a position fix, ['engines', 'systems'] for systems issues) and notes the batched-call efficiency. However, it does not explicitly state when to prefer this tool over similar ones like get_simvars_bulk or get_simvar, leaving the selection criteria implied rather than explicit.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context by specifying that the tool also reports whether the sim is running or paused, which is beyond the tool name alone.

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, concise sentence that immediately states the tool's purpose. It contains no filler, no redundant restating of the title, and is easily scannable by an agent.

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 zero-parameter, read-only status-checking tool with output schema and annotations covering safety, the description is complete. It tells the agent exactly what condition is being inspected, and nothing else is needed to invoke 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?

This tool has zero parameters, and the schema coverage is complete at 100%. The description is not required to explain parameters, and it correctly avoids mentioning any.

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's function: checking SimConnect connection state and whether the sim is running or paused. It uses a specific verb ('Check') and resource, and it is easily distinguished from its siblings like msfs_connect and msfs_disconnect, which perform actions rather than report state.

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 gives no explicit guidance about when to use this tool versus alternatives such as msfs_connect or msfs_disconnect. The intended context is implied by the tool's name and description, but there is no stated when-to-use, prerequisite, or exclusion.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description reveals important behavior: facility visibility depends on the sim's loaded set, airports are a complete worldwide list, and a miss for airports indicates a wrong identifier rather than an out-of-range result. This adds meaningful operational nuance not in the 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 focused sentences with the primary action front-loaded and no filler. The exception and its operational implication are stated efficiently, and every sentence contributes to correct usage.

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 description covers the core lookup action, the loaded-facility scope, the airport exception, and the interpretation of misses. With an output schema present, no additional return-value detail is needed. The tool is fully understandable from the description alone.

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% and both parameters have clear descriptions. The tool description does not add extra meaning to the parameters, but it is not required because the schema already documents them sufficiently. Baseline 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?

The description states a specific action ('look up'), a resource ('airport, waypoint, NDB or VOR'), and an identifier type ('ICAO identifier'). It clearly defines the tool's scope and distinguishes it from general sim variable or event tools among the siblings.

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 gives clear context: facilities must currently be loaded, with airports as an exception. It also explains how to interpret an airport miss, which is practical usage guidance. It does not explicitly name alternatives or state when not to use the tool, but the lookup use case is clear.

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructiveness. The description adds the prerequisite that the MobiFlight WASM extension must be present and limits the read to the current aircraft, but it doesn't describe failure behavior when the extension or variable is missing.

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?

Three short sentences front-load the core read action, then add a definition and a prerequisite. No filler or repetition of schema/annotation content.

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?

With one simple parameter, an output schema, and safety annotations, the description covers the essential context: what L-vars are, that it reads the current aircraft, and the extension requirement. Nothing critical is missing for correct invocation.

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 already documents the name parameter with examples and auto-prefixing behavior at 100% coverage, so the description adds little parameter-level meaning. The conceptual L-var definition is helpful but not needed to understand the single parameter.

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?

States a specific action 'Read an L-var (local variable) value' and scopes it to 'the current aircraft', distinguishing it from simvar readers and from msfs_set_lvar. The additional sentence defines what L-vars are, removing ambiguity.

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?

Gives clear context for when to use it: L-vars are aircraft-specific add-on variables, and it requires the MobiFlight WASM extension. It does not explicitly name alternatives such as msfs_get_simvar or msfs_search_lvars, so it lacks an explicit when-not-to-use statement.

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

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

Beyond annotations like readOnlyHint and openWorldHint, the description discloses that the underlying list is the entire live world dataset (85,249 airports), that distance filtering always runs before pagination, and that an empty radius result is a true negative. This preempts common misconceptions and goes well beyond what annotations alone convey.

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 front-loaded with the core purpose in the first sentence, and each subsequent sentence adds non-redundant behavioral context about data scope, false negatives, and pagination. It is appropriately sized for the complexity of the behavior it clarifies and contains no filler.

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?

Given the rich input schema, output schema, and annotations, the description covers all essential operational concerns: the spatial filter, default position behavior, data source scope, result ordering, and pagination guarantees. No critical usage information needed to call the tool correctly is missing.

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 already documents every parameter (100% coverage), so the baseline is 3. The description adds meaningful semantic value by explaining that the radius is interpreted over a complete worldwide list and that filtering happens before pagination, clarifying the behavior of radius_nm, offset, and limit beyond their schema descriptions.

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 first sentence, 'List airports near a point, nearest first,' names a specific verb, resource, and ordering. The second sentence adds the algorithmic basis (great-circle distance over SimConnect's airport facility list), making the purpose unmistakable and distinct from sibling facility search 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 description gives clear operational context: searches are relative to a given or current position, and an empty result genuinely means no airport exists within radius rather than a SimConnect loading failure. It does not explicitly name alternatives or exclusions, but the domain is specific enough that no competing sibling tool is implied.

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

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.

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

Annotations already communicate read-only, idempotent, non-destructive behavior. The description adds valuable context beyond those annotations by explaining the PMDG SDK data broadcast mechanism and the options.ini prerequisite, which is exactly the kind of deployment detail an agent cannot infer from hints alone.

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 tightly structured and front-loaded: the core read operation, the supported aircraft, and the critical configuration requirement. Every sentence carries distinct information with no filler.

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?

Given that an output schema exists, annotations cover safety, and the input schema is fully documented, the description is mostly complete. It supplies the key environmental prerequisite and data categories, though it could briefly mention when not to use it in favor of a non-PMDG read tool.

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 schema covers both parameters fully, including the name description, examples, and variant enum, so the baseline is 3. The description adds little parameter-specific meaning beyond reinforcing that the data field is read by name and applies to 777/737 variants.

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 begins with a specific verb and resource: 'Read a PMDG aircraft data field by name (777 or 737 NG3)'. It also enumerates what can be read (switch positions, annunciators, MCP values, fuel, FMC data), making the tool's scope clear and distinct from generic simvar/lvar readers.

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?

It gives clear operational context, including the requirement that 'EnableDataBroadcast=1' must be set in the aircraft's options.ini. However, it does not explicitly compare against sibling tools like msfs_get_lvar or msfs_get_simvar, so an agent must infer when this PMDG-specific tool is preferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a useful behavioral detail beyond annotations: 'Returns the value together with the unit it was actually read in,' clarifying output flexibility. No contradiction exists.

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?

Three short, purposeful sentences front-load the core action and then add return behavior and a practical usage hint. No filler or repetition of schema details.

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?

Given the rich annotations, complete schema descriptions, and an output schema, the description is sufficient for a single-value read tool. It could mention batch or watch alternatives to fully orient the agent among siblings, but nothing essential to making a correct call is missing.

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% and each parameter (name, unit, index) already has descriptive text with examples and defaults. The tool description essentially repeats the purpose covered by the schema without adding new parameter-level semantics.

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 clear action and resource: 'Read a SimVar value by name, in the requested unit.' This clearly identifies a single-value read operation and is distinct from the set/search lvar siblings, but it doesn't explicitly differentiate from the closely related msfs_get_simvars_bulk or msfs_watch_simvar.

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?

It provides actionable routing: 'Use msfs_search_simvars first if you are unsure of the exact name or units.' This is useful and context-specific, though it stops short of naming other alternatives such as get_simvars_bulk for batch reads or watch_simvar for continuous reads.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds genuinely useful behavioral context beyond annotations: results are keyed by 'NAME' or 'NAME:index', and a failed variable does not abort the batch but carries an 'error' entry. This helps the agent anticipate partial failures.

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 short sentences with no filler: the first states the core action, the second provides the critical failure/result behavior. The most important information is front-loaded and every sentence earns its place.

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?

Given the one-parameter schema, rich schema descriptions, and output schema, the description plus structured data fully support correct invocation. The partial-failure and keying behavior are explicitly covered. Missing only an explicit routing note about when to prefer this over the single-read sibling, which is not essential.

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 detailed documentation of the 'variables' parameter including accepted keys, an example, and a max of 100 entries. The tool description adds no additional parameter meaning, so the baseline of 3 applies.

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, resource, and batching intent: 'Read several SimVars in one call.' It is clearly distinguishable from the singular msfs_get_simvar tool by the plural and batching wording, though it does not explicitly name or contrast that sibling.

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 batching language implies it should be used when multiple SimVars are needed in one call, but there is no explicit when-to-use guidance, no mention of when not to use it, and no alternative tool names. The agent must infer the choice between this and msfs_get_simvar.

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

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

While annotations already declare readOnlyHint, openWorldHint, and idempotentHint, the description adds substantial behavioral context: the first call downloads ~32,000 presets (~17 MB), takes several seconds, the two tools share the same in-memory copy, and it refreshes every 6 hours. It also explains refresh=True and notes the internet requirement—none of which is available from annotations or schema alone.

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 longer than average, but every sentence carries distinct information: purpose, use case, caching behavior, refresh option, and network requirement. There is no redundancy, and the most decision-relevant guidance is front-loaded.

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 description covers purpose, sibling differentiation, data loading behavior, refresh semantics, and operational prerequisites. With an output schema present and parameter coverage at 100%, nothing an agent needs to correctly select and invoke this tool is missing.

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%, so the baseline is 3; the schema already documents all five parameters. The description adds value by explaining that vendor spellings must be exact for msfs_search_hubhop, reinforcing the vendor parameter's semantics, and by tying refresh=True to the cached database behavior described for the session.

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 opens with 'List the aircraft that HubHop has presets for,' naming a specific verb, resource, and scope. It additionally differentiates the tool from msfs_search_hubhop by framing it as the spelling source for that search tool, so an agent can immediately tell the two apart.

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 second sentence gives explicit guidance: use this tool to find exact vendor and aircraft spelling before calling msfs_search_hubhop, because HubHop matches filters exactly and a mismatched name would silently return nothing. This directly addresses when and why to use it, and the sibling relationship is explicit.

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

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

Even with readOnlyHint, idempotentHint, and openWorldHint annotations, the description adds substantial behavioral context: the 1000-name cap and 'truncated' flag, the risk of add-on crowding, the internal no-op RPN re-arm quirk, and explicit failure modes like NO_LVARS_RETURNED and LVAR_LIST_INCOMPLETE. Nothing contradicts the 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?

The description is long but front-loaded with the core purpose and packed with necessary caveats. Some internal-mechanism detail, such as the RPN re-arm story, could be tightened, but it earns its place by explaining a real behavioral quirk that could otherwise confuse an agent.

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 description covers prerequisites (MobiFlight WASM), result semantics (truncation, incomplete responses), failure modes, and sibling alternatives. Since an output schema exists, the lack of a full return-structure listing is not a gap; the description provides everything needed to invoke and interpret this 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?

Schema description coverage is 100%, with limit, offset, and filter_prefix all documented in the input schema. The tool description does not add parameter-specific detail beyond the schema, so the baseline of 3 is appropriate; it neither improves nor harms parameter understanding.

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 opens with a specific verb and resource: 'Enumerate the L-vars registered by the currently loaded aircraft.' It clearly differentiates this from siblings like msfs_search_lvars and msfs_get_lvar by noting it returns bare names only and that msfs_get_lvar can read any name directly.

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 gives explicit selection guidance: use msfs_search_lvars / msfs_browse_lvar_catalog when catalogued detail is needed, and use this tool for aircraft without a catalog or to see everything currently registered. It also notes when msfs_get_lvar is the better fallback, making the usage boundary unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by confirming the output includes every category and associated variable counts, which goes beyond simple restating of the tool name.

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 short sentences fully convey purpose and usage without redundancy. The main capability is front-loaded, and the second sentence earns its place by connecting output to a sibling operation.

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?

With no parameters, rich annotations, and an output schema present, the description provides all necessary context: what the tool returns, that the result is exhaustive, and how it should be used in relation to msfs_search_simvars. Nothing essential is missing.

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 tool has zero parameters and the schema is empty, so the baseline is 4. The description does not need to explain parameter meaning because there is nothing to parameterize; it correctly focuses on output semantics instead.

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: "List every SimVar category with its variable count." This clearly identifies what the tool does and differentiates it from sibling tools such as msfs_search_simvars and msfs_list_lvars, since it targets category metadata rather than variable values or lvars.

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 gives an explicit use case: "Use this to discover category names for the 'category' filter on msfs_search_simvars." This directly ties the tool to a downstream workflow and names the relevant sibling. It does not list when-not-to-use exclusions, but the context is clear enough to guide selection.

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

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

The description goes well beyond the annotations: it warns that the current flight is discarded without prompting, explains that the call blocks until SimConnect responds again, notes the wait is bounded, and cautions that load time can vary. No contradiction with annotations exists.

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 front-loaded with the core purpose and remains focused. The additional paragraphs about blocking behavior and measured timing earn their place, though the internal references like `_wait_for_sim_responsive` add a slight implementation-detail flavor.

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 single-parameter destructive tool with a rich annotation set and an output schema, the description is complete. It covers purpose, use case, blocking semantics, timing expectations, and the no-prompt discard behavior. Nothing essential is missing for correct invocation.

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% and the schema already documents the `path` parameter as an absolute path to a .FLT file. The description adds context about saved flights but not new parameter-level semantics, so the baseline 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?

The description opens with a specific action and resource: loading a saved flight and replacing the current one. The .FLT file reference and 'saved flight' language distinguish it from the sibling msfs_load_flight_plan, and the replacement behavior is unique among the sibling set.

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?

It explicitly states when to use it: 'restore a known starting state before a test run.' It does not name alternatives or say when not to use it, but the context is clear and the destructive consequence is called out.

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

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

The description goes beyond annotations by disclosing two non-obvious behaviors: the aircraft is not repositioned, and the tool deliberately waits for MSFS to resume answering SimConnect before returning. It also points to a cross-reference for the reasoning. This is valuable behavioral context that annotations alone do not provide.

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 compact and front-loaded with the primary action, followed by two essential behavioral clarifications. Every sentence earns its place, and the structure makes the most important facts immediately visible. No filler or redundant restatement.

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?

Given the single required parameter, an available output schema, and annotations covering read-only/destructive characteristics, the description is complete enough for safe invocation. It adds the critical waiting behavior and non-repositioning guarantee. No essential information for calling the tool correctly is missing.

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%; the path parameter is already documented as 'Absolute path to a .PLN flight plan.' The description repeats the .PLN detail but adds no new format, validation, or example information. Baseline 3 is appropriate because the schema carries the parameter meaning.

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: 'Load a .PLN flight plan into the aircraft's GPS or FMS.' It also clarifies scope with 'The aircraft is not repositioned,' which distinguishes it from msfs_load_flight. This lets the agent identify the tool without inspecting the schema.

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 no-repositioning statement gives clear context for when to use this tool instead of a flight-loading sibling. It does not name alternatives explicitly, but it implies the distinction well. The reference to msfs_save_flight's docstring also guides the agent on the waiting behavior.

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

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

The description discloses non-obvious library quirks: save_flight() unconditionally returns False, an immediate read-back can raise, success is verified by polling the file, and MSFS may remain unresponsive for ~14 seconds. These details far exceed what the annotations provide and help the agent interpret status correctly.

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 front-loaded with a clear one-sentence purpose, and the later paragraphs contain valuable implementation caveats. However, the level of internal library detail is dense and could be tightened without losing essential guidance.

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?

Given the 100% parameter coverage, the annotations, and the existence of an output schema, the description covers all essential operational context: error behavior, overwrite safety, waiting semantics, and success signaling. Nothing critical is missing for an agent to invoke this 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?

Schema coverage is 100%, so the parameters are already well documented. The description reinforces the overwrite parameter's meaning ('Refuses to replace an existing file unless overwrite=True') but does not add much semantic detail beyond that.

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 names the specific action ('Save the current flight to a .FLT file'), identifies the file format, and explains that the state is captured for a later msfs_load_flight call. This clearly distinguishes it from sibling tools such as msfs_load_flight and msfs_load_flight_plan.

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?

It explicitly states the tool's use case—persisting a known flight state—and references the companion load tool. It also conveys overwrite behavior, but it does not explicitly state when not to use it or name alternatives to avoid.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no safety contradiction exists. The description adds meaningful behavioral context: it claims the search spans the full 994-event catalog (not just the builtin fallback list) and that results are paginated, both of which inform how an agent should call and handle results.

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 short, front-loaded with the main purpose, and every sentence earns its place: the first states the core behavior and the second adds catalog scope and pagination behavior. There is no redundant or vague filler.

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 search tool with rich annotations, a complete input schema, and an output schema, the description covers the essential behavioral details an agent needs: the resource being searched, optional filtering, catalog breadth, and pagination. It could have explicitly mentioned the response_format option or given examples, but these are already available in the schema, so the description is adequately complete.

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?

With 100% schema description coverage, the baseline is 3 because the schema already documents all parameters. The description adds little beyond what the schema provides, though it does reinforce 'optionally filtered by category' and mentions pagination, which maps to the limit and offset parameters. No parameter details are contradicted or left unclear.

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 an explicit action ('Search'), a specific resource ('SimConnect events'), and the main input ('by keyword, optionally filtered by category'). It also distinguishes the tool from sibling search tools like msfs_search_simvars and msfs_search_lvars by naming its resource, and clarifies it covers the full 994-event catalog rather than only the builtin fallback list.

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 gives clear context for when the tool is appropriate: searching events by keyword with optional category filtering, and it notes that the full catalog is searched, not just the fallback list. It does not explicitly name alternatives or exclusion conditions, but the purpose is explicit enough that an agent can select it over trigger-oriented or simvar-search siblings.

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

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

Beyond the readOnly/openWorld/idempotent/destructive annotations, the description discloses first-call latency from downloading ~32,000 presets, 6-hour memory caching, automatic re-fetch behavior, the need for internet access, and that returned RPN code is directly executable. This is exactly the kind of operational context annotations cannot convey.

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 long but tightly organized into purpose, differentiation, performance/cache behavior, and constraints. Every sentence provides actionable guidance—there is no filler, and the most decision-relevant facts are front-loaded.

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?

Given the tool's complexity (8 optional params, no required fields, output format choice, external network dependency), the description covers all critical operational aspects: when to use it, what to expect on first call, how caching works, how to force refresh, and what to do with the results. Nothing an agent needs to invoke it correctly is missing.

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%, so the baseline is 3. The description adds extra meaning by explaining the minimum filter requirement across query/vendor/aircraft/system, detailing when to use refresh=True ('right after publishing a new preset yourself'), and clarifying the semantic value of the code field in results.

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 opens with a specific verb and resource: 'Search the MobiFlight HubHop community preset database.' It also differentiates the tool from siblings by stating HubHop 'covers far more aircraft than the bundled catalogs' and framing it as the fallback when msfs_search_lvars finds nothing.

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?

Usage is explicitly tied to a condition: 'this is the place to look when msfs_search_lvars finds nothing for the loaded aircraft.' It also gives a hard constraint, 'Supply at least one of query, vendor, aircraft or system,' and explains the cache/refresh behavior so the agent knows when refresh=True is appropriate.

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

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

Beyond the read-only/idempotent annotations, the description discloses pagination, the ordered auto-detection strategy, the authoritative PMDG probe vs title-text match distinction, how 'message' explains resolution, and the conditional 'Catalog' column in markdown output. This is far more behavioral disclosure than annotations provide.

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 long but tightly structured: purpose first, then scope, pagination, auto-detection, fallback behavior, and trust caveats. Every sentence contributes decision-relevant detail rather than filler, and the front-loaded opening gives immediate orientation.

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?

Combined with a fully described input schema and an output schema, the description covers catalog resolution, trust calibration, pagination, scoping behavior, and result-format caveats. An agent has enough context to select parameters correctly and interpret the response appropriately.

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%, so the baseline is 3, and the schema already documents each parameter well. The description adds non-schema meaning by explaining that an unspecified catalog resolves to 'all' when no auto-detection succeeds, and that results are paginated, which enriches the semantics of catalog, limit, and offset.

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 opens with 'Search known aircraft L-vars by keyword' — a specific verb, resource, and search intent. It further clarifies scope ('current aircraft or every known aircraft catalog') which distinguishes it from list and browse siblings without ambiguity.

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 gives clear context on when the search spans all catalogs, and the schema's catalog/prefix parameters point to msfs_browse_lvar_catalog for discovering keys and conventions. However, it does not explicitly contrast this tool against siblings like msfs_list_lvars or msfs_search_simvars, so exclusion conditions are left implicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond the annotations by noting that results include units, settable status, and pagination, which helps the agent understand what to expect from the call.

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 compact and front-loaded: the main action is stated in the first sentence, followed by return-value purpose and pagination detail in two short sentences. Every sentence earns its place with no redundancy or filler.

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 search tool with a detailed input schema, a present output schema, and rich annotations, the description is complete. It explains the core operation, the key returned fields, and pagination, while leaving parameter formatting and response-shape details to the schema where they are already well documented.

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 each parameter already described clearly, including examples for keyword and category. The description adds no new parameter-level detail, but it reinforces the overall purpose of returning units and settable flags, which is enough to meet the baseline for high schema coverage.

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 opens with a specific verb and resource: 'Search the SimVar catalog by keyword.' It clearly distinguishes this tool from sibling get/set and event/LVar search tools by stating it returns units and settable status, which directly supports msfs_get_simvar and msfs_set_simvar.

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 gives clear context for when to use the tool: before calling msfs_get_simvar or msfs_set_simvar, to obtain the right arguments. It does not explicitly list alternatives or exclusions, but the SimVar-specific scope and stated purpose make the intended use clear.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds meaningful behavioral context by specifying that it triggers switches, buttons, and knobs in the cockpit via the PMDG SDK. There is no contradiction; the added detail helps the agent understand that calling this tool can change aircraft state.

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 with no filler. It front-loads the core purpose, gives the relevant aircraft variants, and ends with actionable discovery guidance. Every sentence contributes information the agent needs.

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 relatively simple three-parameter tool, the description plus rich schema and annotations cover the essential knowledge: what the tool does, how to find valid event names, how parameters behave, and the mutating/destructive nature. The output schema further reduces the need for return-value documentation.

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%, so the baseline is 3. The description adds value by pointing to event discovery via msfs_search_lvars(), but it does not elaborate on parameter semantics; the schema already thoroughly describes variant detection, parameter position values, and event_name examples.

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 names a specific verb and resource: sending a PMDG control event for the 777 or 737 NG3, and clarifies it triggers cockpit controls via the PMDG SDK. This distinguishes it from generic event tools like msfs_trigger_event and from PMDG read tools like msfs_get_pmdg_var.

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 gives one useful prerequisite: find events using msfs_search_lvars() and look for an 'events' field. However, it does not explicitly state when to prefer this tool over sibling alternatives such as msfs_trigger_event or msfs_trigger_custom_event, nor does it explain why PMDG events require a dedicated tool.

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

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

Annotations already cover non-read-only, non-idempotent, non-destructive behavior; the description adds that it is an overlay message for debug feedback but does not disclose details such as whether new messages replace old ones or whether appearance settings affect behavior beyond the parameters. It does not contradict annotations, but it adds only modest behavioral context.

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 front-loaded sentence with no filler. Every word adds value: it states the action, the target resource, and the intended use case.

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 simple tool with a complete input schema, an output schema, and useful annotations, the description carries enough context to invoke the tool correctly. It could be stronger by explicitly stating that the message is transient and purely visual, but the combination of description, schema, and annotations covers the essentials.

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 parameters (text, color, duration_s) already clearly documented in the input schema. The description adds only the 'debug feedback' intent and no parameter-specific meaning, so the 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?

The description uses the specific verb 'Display' and names the exact resource ('text overlay message in the simulator'), making the tool's function immediately obvious. The phrase 'debug feedback' reinforces intent, and the described action is unique among the sibling tools listed, so an agent can distinguish it without opening the schema.

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 parenthetical '(debug feedback)' gives clear situational context: this tool is for displaying temporary informational messages during debugging. It does not explicitly mention when not to use it or name alternatives, but no sibling tool provides the same text-overlay capability, so the context is sufficient for selection.

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

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

Annotations only say the operation is not read-only, open-world, idempotent, and destructive. The description goes far beyond this: it discloses atomicity, that the reported position is a read-back rather than the request, that unconfirmed fields are null and listed in `unverified`, and that `status` may still say 'ok' even when the read-back did not confirm the move. This is exactly the kind of behavioral context an agent needs.

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 well structured: purpose first, then implementation rationale, then response-reading caveats. It is slightly verbose but every sentence conveys a distinct and useful fact; the depth is justified by the non-obvious 'ok' read-back behavior.

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?

Given the 8-parameter schema with 100% coverage and a true output schema, the description does not need to repeat parameter docs. It supplies the remaining essential context: when it is meant for (test setup), the atomic method, the old pitfall, and how to interpret the response. An agent has everything needed to invoke it and trust the result.

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%, so the input schema fully documents each parameter. The description adds no per-parameter semantics beyond mentioning that the on-ground state can be set; it mostly explains output behavior, which belongs to response semantics rather than parameter semantics. Baseline 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?

The first sentence uses a specific verb and resource: 'Reposition the aircraft (test scenario setup).' It also clarifies the implementation (SIMCONNECT_DATA_INITPOSITION, atomic) and contrasts with the unreliable individual variable-writing approach, distinguishing it from sibling msfs_set_simvar-style 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?

It gives clear context: test scenario setup for aircraft repositioning, and warns that the previous method of writing PLANE_LATITUDE/LONGITUDE individually is unreliable and cannot set on-ground state. It does not enumerate all alternatives or give explicit when-not-to-use conditions, so I deduct slightly.

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

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

Annotations already signal mutation, idempotence, and open-world effects. The description adds substantial behavior beyond that: it reveals the native SimConnect mechanism, the compatibility with Fenix aircraft, and the crucial verification semantics ('verified': true/false/null with 'false or null is never reported as success'). This is exactly the kind of non-obvious behavioral context an agent needs when deciding whether to trust the result of a write.

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?

Three tight paragraphs, each carrying a distinct purpose: the core action, the implementation/compatibility detail, and the verification semantics. There is no filler or repetition. The primary purpose is front-loaded, and every sentence earns its place.

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?

With an output schema present, the description does not need to enumerate return fields beyond the critical 'verified' semantics it already explains. Two required parameters are fully documented in the schema, and the description covers the operational context (current aircraft, Fenix compatibility, no MobiFlight). Nothing an agent needs to call this tool correctly is missing.

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%; both parameters ('name' and 'value') already have clear descriptions in the input schema. The tool description restates the operation but adds no new meaning about the parameters themselves, so baseline 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?

The description states a specific action ('Write'), resource ('L-var'), and scope ('on the current aircraft'), and it further distinguishes itself by explicitly noting it does not use MobiFlight RPN, separating it from sibling tools like msfs_execute_calculator_code. The L-var vs simvar distinction is carried by the name and reinforced by the description. This is a clear, unambiguous purpose.

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 concrete usage context: it works with proprietary aircraft like the Fenix A320/A321 and does NOT require MobiFlight. This implies when to prefer this tool over MobiFlight-based approaches. It does not explicitly name alternatives such as msfs_set_simvar or state exclusions, but the 'does NOT require MobiFlight' clause gives sufficient selection guidance for an agent comparing siblings.

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

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

The description adds a meaningful behavioral detail beyond the annotations: it fails with a specific error if the sim rejects the write, rather than reporting success. This helps an agent understand failure semantics. The annotations already cover read-only, destructive, idempotent, and open-world traits, so the description supplements rather than repeats them.

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 two short sentences with no filler. The main action is front-loaded, and the error behavior and prerequisite are provided in the second sentence, both earning their place.

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 description covers the core operation, a key precondition, and failure behavior, while the annotations and output schema handle safety and return shape. It does not mention a requirement to be connected to the simulator, but that is likely implied by the tool family and sibling msfs_connect.

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%, so the input schema already documents all four parameters well. The description adds no additional parameter-level meaning beyond the schema, making the baseline 3 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?

The description opens with the specific verb 'Write' and resource 'settable SimVar', which clearly identifies the operation and distinguishes it from sibling tools like msfs_set_lvar. The 'settable' qualifier adds precision about which SimVars are valid targets.

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 gives explicit guidance: check the 'settable' flag with msfs_search_simvars before writing. This provides a clear precondition and context for correct use, though it does not name alternative tools or explicit when-not-to-use conditions.

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

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

Beyond the annotations, the description discloses the exact RPN delivery syntax, the fact that this is not native SimConnect event mapping, and the important aircraft-specific no-op behavior with a concrete PMDG 737 example. This is rich behavioral context that the structured fields do not provide.

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?

Three focused paragraphs each serve a distinct purpose: definition, mechanism and alternative, and failure-mode caveat. The PMDG example is detailed but earns its place by explaining a non-obvious result an agent would otherwise misinterpret. There is no fluff.

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 tool with non-trivial runtime behavior, the description covers mechanism, prerequisite, alternative path, and failure interpretation. With full schema coverage and an output schema present, nothing essential is missing for an agent to invoke it 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 coverage is 100%, so the schema already documents both parameters and gives an example for `name`. The description adds genuine value by showing how `name` maps to `(>K:NAME)` and how `parameter` is prefixed when present, clarifying the runtime semantics beyond 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 first sentence states a specific action ('Fire a custom event as a key event') and a specific resource ('through the MobiFlight WASM module'). The second paragraph explicitly contrasts this with msfs_trigger_event, making the tool's distinct role in the sibling set clear.

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 names msfs_trigger_event as the native SimConnect alternative and explains that this path reaches events outside the standard SimConnect catalog, which helps an agent choose between them. It also flags the WASM module requirement. It stops short of an explicit 'use this when / use that when' rule, but the guidance is strong.

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

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

Goes well beyond annotations by disclosing the underlying MapClientEventToSimEvent + TransmitClientEvent mechanism, send-ID correlation, error behavior (NAME_UNRECOGNIZED/ERROR vs propagated exceptions), and the critical caveat that acceptance does not guarantee the aircraft acted on the event. This is rich, non-obvious behavioral detail.

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?

Every sentence earns its place: the opener states the action, the second paragraph explains resolution and mechanism, and the final paragraph covers important behavioral caveats. The structure is front-loaded and the density is appropriate for the tool's complexity.

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 tool with output schema present and detailed annotations, the description covers resolution order, error handling, correlation limits, and aircraft-specific behavior. It even points to external documentation for known Sim Behaviours. No critical operational information appears to be missing.

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%, so the baseline is 3; the schema already documents name examples and integer parameter behavior including negative values. The description adds context about name resolution through the catalog and direct mapping, but does not further clarify parameter semantics beyond 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?

Description opens with 'Fire a SimConnect event' — a specific verb and resource. It further defines scope by explaining the 994-event catalog resolution and fallback to direct name mapping, making clear this is the generic SimConnect event trigger, distinct from siblings like msfs_trigger_custom_event.

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 gives useful context: it works for both catalog events and third-party/newer MSFS events, and explains error semantics. However, it does not explicitly say when to prefer this tool over alternatives such as msfs_trigger_custom_event or msfs_set_simvar; usage is implied rather than directly contrasted.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses a valuable failure behavior: it fails fast on the first read error instead of wasting the full sampling duration. This directly informs agent expectations about error handling and performance.

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 only two short paragraphs, with the core behavior front-loaded in the first sentence and the key failure mode in the second. Every sentence contributes meaningful information with no filler.

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?

With a complete 100% parameter schema, an output schema, and annotations covering read-only and non-destructive behavior, the description adds what structured data cannot: the time-series purpose and fail-fast behavior. Nothing essential for correct invocation is missing.

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%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema, though the mention of 'name or unit' in the fail-fast note lightly reinforces those parameters' roles.

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 'Sample a SimVar over time' with a specific verb and resource, and 'returning a time series' makes the output explicit. This clearly distinguishes it from one-shot alternatives like msfs_get_simvar and msfs_get_simvars_bulk.

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?

'For debugging' gives a clear context and 'over time' implies the use case, but the description never names alternative tools or states when not to use this one. The guidance is present only by implication, not explicit routing.

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