catalog_search

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

No annotations exist, so the description carries the full burden, and it does disclose meaningful behavior: no authentication required, unknown catalog names return a candidate list and stop, radii below 0.1 are clamped, and row counts are capped at 50. It omits return shape, error handling beyond catalog resolution, and VizieR-side throttling, which keeps it from a 5.

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?

Purpose is front-loaded in one sentence, followed by compact examples and a well-structured Args list; almost every line adds information. Minor deduction for a truncated third example ('NGC カタログで' trails off) and some redundancy between the radius note and the args line.

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 six-parameter search tool with no annotations and no output schema, the description covers inputs and key failure modes thoroughly. The notable gap is that no output schema exists and the description never describes the returned rows/columns, so the agent does not know what a result looks like.

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 fully, and it does: every one of the six parameters is given meaning, units (degrees, arcminutes), defaults (2mass, 1.0, 10), ranges (0.1–60, max 50), and interaction rules (object_name resolves via Sesame; ra/dec used only when object_name is omitted). It also explains the VizieR c.rm unit quirk and the fallback for unknown catalog names.

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?

States a specific verb and resource: cone search of VizieR (CDS) observational catalogs, with an explicit positional scope ('その位置にある天体') and no-auth note. This distinguishes it from archive-specific siblings like mast_observations or alma_search by naming the VizieR data source, but it never explicitly contrasts with those 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?

Three example queries ('M31 のまわりの 2MASS の天体', 'シリウスの Gaia DR3 の値') convey implied usage scenarios, so the agent can infer intent. However, there is no when-not guidance and no mention of the many lookalike siblings (object_lookup, cadc_observations, mast_observations), leaving routing to inference.

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