xbrl_get_html_tables

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds minimal behavioral context beyond 'extract' and 'returns tables', which is consistent with annotations. No contradiction, but the description does not disclose potential pitfalls like missing tables or performance.

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 very concise, consisting of 3 sentences plus an args/returns line. It is front-loaded with the clear purpose. Every sentence adds some information, though the args list is redundant with the schema. No wasted words.

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?

Despite an output schema existing, the description only says 'Returns: str: JSON with table data', which is vague. It does not explain what structured row/column data means, error handling, or prerequisites (e.g., filing must be loaded). The tool has moderate complexity with filtering and limits, but the description leaves significant gaps.

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 only lists parameter names ('Filing ID, optional search filter, table index, limits') without adding meaning. For instance, it omits that 'filing_id' must come from xbrl_load_filing, or that 'table_index' is 0-based. The schema does have some descriptions, but the description provides no added value.

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 states 'Extract HTML tables from the filing document' and 'Finds tables in the HTML content', clearly identifying the verb and resource. It distinguishes from siblings like xbrl_extract_facts and xbrl_get_raw_xml by focusing on HTML tables, but does not explicitly compare with xbrl_get_footnotes or similar tools.

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 mentions optional text search filter, table index, and limits, but provides no guidance on when to use this tool versus alternatives (e.g., xbrl_extract_text or xbrl_get_footnotes). There is no 'when not to use' or exclusions.

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