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

No annotations are provided, so the description carries full burden for behavioral disclosure. It details inputs and return type but does not explicitly state that the operation is read-only, does not modify the file, or discuss any side effects, permissions, or error conditions. The word 'provides' implies non-destructive behavior but is not explicit.

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 appropriately sized: a one-sentence purpose statement, a structured Args list, and a Returns line. Every part earns its place, with no redundancy or 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?

Given the tool's simplicity, the output schema, and the complete parameter explanations, the description is mostly sufficient for invocation. However, it omits usage context (e.g., when to call it) and potential error cases, so it stops just short of fully 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 description includes an Args section that explains all 6 parameters, including their meaning and defaults (e.g., 'line: 0-based line number', 'limit: Maximum number of completions to return (default: 50)'). This fully compensates for the schema's 0% description coverage, which only provides types and defaults.

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 'Provides code completions at a specific position in a CodeQL file', which uses a specific verb and resource. It clearly distinguishes this tool from siblings like hover, definition, and references, which serve different purposes.

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?

No explicit when-to-use or alternative guidance is provided. The agent must infer that this tool is for autocomplete-style suggestions based on the description's wording, but the description does not state when to prefer it over siblings or when not to use it.

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?

No annotations are provided, and the description offers minimal behavioral disclosure beyond stating it navigates and returns a dictionary. It does not mention whether the operation is read-only, potential side effects, or error behavior. For a tool with no annotation coverage, this is insufficient.

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 concise and efficiently structured with an action statement followed by Args and Returns sections. No unnecessary words, and the information 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?

For a simple navigation tool with three parameters and an output schema, the description covers the essential details of purpose, arguments, and return type. However, it lacks usage context and differentiation from sibling tools, leaving some contextual gaps.

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 description compensates for the 0% schema description coverage by explicitly defining each parameter: file_uri as the CodeQL file URI, line as 0-based line number, and character as 0-based character position. This fully explains the parameter meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it navigates to the definition of a symbol, using a specific verb and resource. The tool name 'codeql_definition' aligns with the description, and the focus on 'definition' distinguishes it from siblings like codeql_references.

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 no guidance on when to use this tool versus alternatives like codeql_references or codeql_hover. It only states the action without context, exclusions, or alternative recommendations.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions retrieval of diagnostics and metadata but does not disclose potential side effects, file requirements, permissions, or whether any analysis is triggered. For a mutation or analysis tool, this is a significant gap.

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 concise, front-loading the main purpose in one clear sentence and then structuring Args/Returns in a clean, scannable format. Every sentence earns its place with 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 simple, single-parameter tool with an output schema, the description is mostly adequate. It covers purpose and the parameter, and the output schema handles return values. However, it lacks guidance on when to use the tool and does not describe any behavioral expectations (e.g., whether the file must exist or be of a specific type).

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 description provides an Args section explaining 'file_uri: URI of the CodeQL file', which adds meaning beyond the schema's bare string type. Even though schema coverage is reported as 0%, the description clearly compensates by defining the parameter's purpose and format expectations.

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 retrieves diagnostics (syntax/semantic warnings, errors) for a file, using a specific verb and resource. It differentiates from siblings like hover, definition, and references by focusing on diagnostics.

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 implies usage: to get diagnostics for a file. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. It offers only implied context.

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?

No annotations are provided, so the description carries the full burden. It discloses the action (formatting) and the return shape (dictionary with text edits and metadata), which gives a reasonable idea of the tool's behavior. However, it does not clarify whether the file is modified on disk or only edits are returned, nor does it discuss side effects, permissions, or error cases. This is a moderate level of transparency.

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 concise and well-structured: a one-line summary followed by an Args list and Returns note. It is front-loaded with the main purpose and every line provides useful information. There is no wordy filler or repetition of schema details that are already obvious.

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 moderate complexity (formatting with optional range) and the existence of an output schema, the description covers the essential usage and return shape. It lacks explicit usage comparisons with siblings and side-effect clarity, but for a narrow formatting tool it is adequate. The presence of an output schema reduces the need to detail return values in prose.

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 zero parameter descriptions (0% coverage), so the description's Args section is the only semantic guidance. It explains each parameter's role (e.g., 'Start line for range formatting'), which meaningfully compensates for the schema gap. However, the explanations are brief and do not cover coordinate conventions or constraints beyond basic intent.

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: 'Formats a CodeQL file according to standard conventions.' This clearly distinguishes the tool from sibling operations like codeql_complete, codeql_hover, or codeql_definition. The purpose is unambiguous and the tool's scope is well defined.

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 implies usage for formatting CodeQL files, with optional range parameters to scope the formatting. However, it does not explicitly state when to prefer this tool over siblings or provide exclusions (e.g., 'Use codeql_update_file for direct edits'). The context is clear but not fully elaborated with when-not-to-use guidance.

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?

With no annotations, the description carries the full burden. It discloses that it returns a dictionary with hover information and metadata, and mentions 'documentation, type information' which gives some idea of the output. But it does not describe error behavior (e.g., invalid position) or any side effects. For a simple read-only hover tool, this is adequate but not rich.

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 well-organized into Args and Returns sections. Every sentence adds useful information with no fluff or repetition.

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 tool is simple and the description covers purpose, all three parameters, and the return shape. Output schema exists, so return details are structured elsewhere. Missing info like error conditions or exact metadata content is a minor gap but not critical for a hover 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 provides only types, with 0% description coverage. The description adds critical semantics: file_uri is a URI, and line/character are 0-based positions. This is highly valuable for correct invocation and goes 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 description clearly states a specific action ('Retrieves hover information') and a resource ('at a specific position'), and distinguishes itself from siblings like codeql_definition and codeql_references by focusing on documentation/type hover details.

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 implies usage: use this tool when you need hover context like documentation or type info at a position. However, it does not explicitly state when not to use it or compare with alternatives such as definition or references, so guidance is only 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?

With no annotations, the description carries the burden of behavioral disclosure. It mentions the return format (dictionary with reference locations and metadata) and parameter conventions (0-based line/character), which adds some transparency. However, it does not disclose potential errors, limitations, side effects, or whether the operation is read-only. The description is adequate but not rich in 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 short, well-organized with explicit Args and Returns sections, and free of redundant information. Every sentence serves a purpose: stating the tool's function, defining parameters, and clarifying the output. It is appropriately front-loaded and easy to scan.

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 simplicity and the presence of an output schema, the description covers the core usage completely: what it does, how to call it, and what it returns. It lacks information about edge cases or error behavior, but for a code navigation tool, the provided details are sufficient for an agent to select and invoke it correctly. Sibling names set additional context for differentiation.

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 provides only types and required flags with zero description coverage. The description compensates fully by explaining each parameter in the Args section: file_uri (URI of the CodeQL file), line (0-based line number), and character (0-based character position). This adds clear meaning beyond the schema and enables correct invocation.

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 ('Finds') and a specific resource ('all references to a symbol at a specific position'). It clearly distinguishes from siblings like codeql_definition (which finds a definition) by stating it finds references. The purpose is unambiguous and action-oriented.

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 implies when to use the tool (when you need references to a symbol) but provides no explicit guidance on when not to use it or how it compares to alternatives. No prerequisites or exclusions are mentioned, leaving the agent to infer usage from sibling names rather than explicit instructions.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly indicates the file must be open, that the entire content is replaced ('New complete content'), and that changes are unsaved (implying no persistence). It also discloses the return type (dictionary with success message and metadata). While it omits error handling and persistence nuances, it provides substantial behavioral context beyond the bare schema.

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 and concise: a clear purpose sentence, one contextual sentence, a brief args list, and a return note. Every line contributes meaningful information with no redundancy or vagueness, making it easy for an agent to parse quickly.

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 two-parameter update tool with an output schema, the description covers the essential aspects: purpose, usage context, parameter semantics, and return value. It does not explain error conditions or detailed side effects, but these are relatively minor for this straightforward operation and do not impede 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?

Since schema description coverage is 0%, the description must compensate. The Args section defines file_uri as 'URI of the CodeQL file' and content as 'New complete content of the file,' adding essential meaning beyond the basic type annotations. This adequately explains both parameters, though it could be more specific about URI format or content encoding.

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: 'Updates the content of an open CodeQL file in the language server.' This identifies the specific verb (updates), the resource (CodeQL file), and the context (open file in language server), which differentiates it from sibling read-only tools like codeql_hover and codeql_diagnostics.

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 phrase 'Allows dynamic modification and analysis of unsaved changes' provides clear contextual guidance for when to use this tool—when working with unsaved, in-memory file states. It does not explicitly state alternatives or when not to use it, but this context is sufficient given the sibling tools are all read-only analysis operations.

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