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

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'SELECT only' and 'query fails otherwise' for rule violations. It discloses critical behavioral traits: period columns are TEXT and must be compared as strings, CTEs are disallowed, and certain tables require mandatory filters. This goes well beyond the annotations by explaining the data model quirks and failure conditions, giving the agent a thorough understanding of how the tool behaves.

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 long but well-organized into logical sections: purpose, hard rules, and table categories. It front-loads the core purpose and then dives into necessary details. Every sentence serves a purpose—either clarifying rules or listing tables—so there's minimal redundancy. While it's verbose, the complexity of the tool justifies the length, and the structure aids comprehension. It could be slightly more concise, but it's still efficient for the information conveyed.

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 this level of complexity (multiple table domains, strict query rules), the description is remarkably complete. It covers the key constraints, table inventory, and references to companion tools (get_table_schema, list_tables) for deeper schema exploration. The return type is mentioned ('structured rows'). The only thing not covered is the exact schema of each table, but that's delegated to get_table_schema, so the description does its job without overreaching.

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?

There is only one parameter (sql) with a minimal schema description ('PostgreSQL SELECT query'). The tool description vastly enriches this by explaining the expected query format, constraints, and examples (e.g., WHERE ticker IN ('AAPL','MSFT')). It also lists the tables and hints on filtering, effectively teaching the agent how to construct valid queries. This far exceeds the schema's minimal documentation, making parameter semantics exceptionally clear.

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 precise statement: 'PostgreSQL SELECT over financial / market / alt-data tables — returns structured rows.' It names a specific verb (run) and resource (SQL query over financial tables), and clearly distinguishes itself from sibling tools like company_search and news_search by focusing on structured SQL access. The mention of returning structured rows further clarifies the output, leaving no ambiguity about what the tool does.

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 explicit usage context: it's for SELECT queries on structured tables, with hard rules and a detailed table listing by domain. It also references get_table_schema and list_tables for additional schema and category info, effectively guiding the agent on how to proceed. While it doesn't explicitly state 'use this instead of X' for each sibling, the scope is clear, and the guidance on filtering by ticker and time_frame is actionable. The only minor gap is the absence of explicit 'when not to use' statements for alternative tools, but the domain-specific focus makes the usage obvious.

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