base_tableAffinity

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses that the tool can bind parameters (if provided) and return fully rendered SQL with literals. It also specifies the return type as 'formatted response with query results + metadata'. However, it lacks details on side effects, permissions, performance implications, or how 'commonly used together' is determined (e.g., threshold). The description partially compensates for missing annotations but leaves significant gaps.

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, with the main purpose in the first sentence. It uses a bullet list for arguments and returns, which aids readability. However, there is slight redundancy: 'bind parameters if provided (prepared SQL), and return the fully rendered SQL (with literals) in metadata' could be tightened. Overall, it is efficient and front-loaded with minimal waste.

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 (inferring table relationships), the description covers the purpose, parameters, and return type but lacks completeness. It does not specify the output format beyond 'formatted response with query results + metadata', nor does it provide examples or clarify if data is real-time or cached. It also omits error handling, prerequisites (e.g., database must exist), and how the affinity is computed. With no output schema, more detail is needed for an agent to invoke it confidently.

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 0%, so the description must compensate. It adds meaning by explaining 'database_name' and 'object_name' (though the schema uses 'obj_name', not 'object_name'). However, there is a mismatch: the description says 'object_name' while the schema defines 'obj_name'. This inconsistency could confuse the agent. The description does not provide constraints, formats, or examples beyond basic identification. Given low coverage and the naming discrepancy, the added value is limited.

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 purpose: 'Get tables commonly used together by database users'. It specifies the verb 'Get' and the resource 'tables commonly used together', and explains how it helps infer relationships. This distinguishes it from sibling tools like base_tableUsage or base_tablePreview, which focus on different aspects (usage statistics, row preview).

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 does not provide explicit guidance on when to use this tool versus alternatives. It says 'this is helpful to infer relationships between tables', but does not mention when not to use it or compare it to sibling tools like base_tableDDL, base_tablePreview, or base_tableUsage. No exclusion criteria or prerequisites are stated.

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