findQueriesByTable

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

Annotations already mark the tool as read-only and non-destructive. The description adds meaningful behavioral details beyond that: results are based on 'actually reference[d]' tables, names are matched case-insensitively, and the focus is on observed query usage rather than declared schema. This gives the agent useful runtime expectations.

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 deliver the core purpose, usage guidance, and a key matching rule without redundancy. The main action is front-loaded alerting an agent immediately what the tool is for.

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 output schema exists and annotations cover safety, the description is largely complete for invoking the tool correctly. It covers purpose, usage boundary, matching behavior, and required input intent. The only minor gap is not naming a sibling alternative for declared table structure, but this is not essential to making a correct call.

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 only 33%, so the description must carry parameter meaning. It partially does by explaining that the tool resolves a 'known table' and matches names case-insensitively, but it does not clarify the optional 'schema' parameter or how it constrains the search. The connection parameter is already documented in 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 opens with a specific verb and resource: 'Find stored application/report queries that actually reference one known table.' It also clarifies the intended purpose ('observe filters, joins and business usage') and explicitly contrasts with table structure inspection, making it easy to distinguish from schema-focused siblings like describeTable.

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 states when to use the tool: to learn observed filters, joins, and business usage. It also gives a when-not: 'not to inspect declared table structure.' However, it does not explicitly name the alternative tool for inspecting structure, so it falls just short of fully explicit routing.

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