Consultar o banco H2 (SELECT)

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description still adds meaningful behavior: results are capped at max_linhas rows, and the tool will fail unless the PJe-Calc application is stopped first. It also shows a concrete query shape, which sets expectations for input format.

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?

Front-loaded with the action and read-only nature, followed by helper-tool guidance, an example, and the lock prerequisite. Every sentence carries information, though the inline SQL example adds some length and the 'somente leitura' phrasing partially repeats the annotation.

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 two-parameter read tool with rich annotations but no output schema, the description covers action, input guidance, row cap, and the critical operational prerequisite. It does not describe error behavior or result column formatting, but nothing essential for a 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 adds a little by clarifying that max_linhas is the row cap on the returned result and by providing a sample SELECT that demonstrates the sql parameter format. It does not explain default/limit interactions beyond what the schema states.

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 verb and resource: executes a SELECT on the H2 database in read-only mode. It separates itself from the write-capable sibling db_executar by declaring 'somente leitura', though it never names that sibling as the alternative for writes. An agent can identify the tool's job 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?

Explicitly routes the agent to db_tabelas/db_esquema to discover table/column names before querying, and gives a hard precondition: PJe-Calc holds the database locked while running, so pjecalc_parar must be called first. This is exactly the when-to-use / when-not-to-use guidance that prevents failed calls.

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