populate_celestial_bodies_bulk

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

No annotations are supplied, so the description carries the full behavioral burden, yet it only says 'Trigger'. It does not disclose that this is an LLM-driven, likely long-running and costly operation, whether it enqueues a background job versus running inline, whether existing celestial bodies are overwritten or preserved, or whether the operation is idempotent. The 'sync' parameter hints at async-by-default behavior, but the description never confirms or explains that.

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?

A single front-loaded sentence with no filler; the scope qualifier arrives immediately after the verb and resource. It is not padded, though it is short enough that it could have spent a few more words on behavior without becoming bloated.

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 bulk, LLM-backed mutation with no annotations and no output schema, the description leaves critical gaps: what is returned (a job handle?), how to monitor progress given a get_job_status sibling exists, and what the effect on existing data is. An agent could call it but could not predict the outcome or follow up correctly.

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 both parameters are already documented in structured form, and the baseline of 3 applies. The description does add one piece of meaning beyond the schema: that omitting star_system_id means all star systems rather than an error or a default, which sharpens the optionality semantics.

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?

Names a specific action ('Trigger bulk LLM celestial body discovery') plus an explicit scope ('across all star systems or a single star system'), which lets an agent distinguish it from populate_star_system_celestial_bodies and populate_star_systems_bulk without opening a schema. It stops short of naming those siblings explicitly, so differentiation is inferred from scope wording rather than stated.

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 phrase 'across all star systems or a single star system' implies the selection rule (omit star_system_id for everything, supply it for one), which is useful implied guidance. However, there is no explicit when-to-use statement, no mention of when a narrower per-system tool would be preferable, and no prerequisites such as required permissions or pre-existing star systems.

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