Run bounded TAP query

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

Annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond annotations by stating the query is synchronous and by explicitly warning that tool errors should be treated as failures rather than empty scientific results. This helps the agent avoid misinterpreting an error as a legitimate empty result.

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 only two sentences and every clause earns its place. It front-loads the core action and scope, then gives the two most important execution rules: boundedness via TOP/maxrec and error interpretation. There is no filler or redundancy.

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 rich input schema, presence of an output schema, and annotations, the description covers the key operational guidance: query scope, boundedness, prior inspection of tables/columns, and error handling. It does not explicitly mention the async job submission alternative for larger queries, but 'small bounded synchronous' sufficiently implies that boundary in most cases.

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 schema already explains every parameter in detail. The description reinforces the query parameter guidance with 'Use TOP in ADQL and/or maxrec,' but this largely repeats what the schema already states. It adds little new parameter-level meaning beyond 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: 'Run a small bounded synchronous TAP ADQL query.' It clearly distinguishes this tool from sibling starfetch_tap_submit_job by emphasizing 'synchronous' and 'small bounded', and it also signals the correct workflow by saying 'after inspecting the exact table and columns.' This is a precise, non-tautological purpose statement.

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 gives clear usage context: use this tool for small, bounded, synchronous queries after verifying table and column names, and use TOP/maxrec to keep the query bounded. It does not explicitly name the async alternative starfetch_tap_submit_job or state when not to use this tool, so it misses the highest level of guidance, but the implied workflow is still clear.

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