LinkIt SQL: query

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

Annotations already provide readOnlyHint: true, and the description reinforces this. It adds meaningful behavioral details beyond annotations: results are auto-capped with maxRows default 50 and max 500, truncation hints are provided, and countTotal triggers an additional COUNT(*) that may be slow. This gives the agent practical expectations for execution without contradicting the annotation.

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 extremely compact: two sentences. The first sentence states purpose and restrictions, the second covers row caps and countTotal. Every clause earns its place, and the most critical information (read-only, query type) is front-loaded. No filler 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?

For a tool with 7 parameters and no output schema, the description provides sufficient execution context: allowed query forms, blocked operations, row limits, truncation hints, and an optional slow-mode flag. It does not describe error behavior or the exact output format, but the readOnlyHint and implicit SELECT semantics cover the main risks. Answers what an agent needs to call 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?

The input schema already has 100% description coverage for all 7 parameters, including defaults and bounds for maxRows and countTotal. The description adds marginal value by mentioning 'truncation hints' and the behavior of countTotal on huge scans, but this does not substantially exceed what the schema already states. Baseline 3 is appropriate given the schema's completeness.

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 'Run a READ-ONLY SELECT/WITH query against a LinkIt SQL Server env' – a specific verb, resource, and query type. It names the blocked statement types, which further clarifies the tool's exact scope. This clearly distinguishes it from the sibling tools 'system' and 'explore' without needing to reference them.

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 makes the read-only intent explicit and states that INSERT/UPDATE/DELETE/DDL/EXEC are blocked, which tells the agent when not to use the tool. However, it does not name sibling alternatives or state explicit conditions for choosing this tool over 'explore' or 'system'. The usage context is implied rather than directly contrasted with other tools.

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