Stream Positions

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

The description adds genuinely non-annotation information: a 30-second tick cadence, the POST endpoint, and a cost of 10 credits (Tier 1), which is exactly the kind of quota/rate context annotations do not carry. It does not explain whether a call returns one snapshot or opens a persistent stream, nor whether the non-readOnly annotation stems from the connection or from credit consumption, leaving some ambiguity.

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?

Front-loaded with the purpose, then compact bracketed metadata for group, endpoint, and cost; nothing is padded. The tag-line formatting is slightly boilerplate but each line carries information an agent would otherwise lack.

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?

With an output schema present and zero parameters, the description needn't explain returns, and cost/cadence are covered. However, for an openWorld streaming endpoint whose annotation says readOnlyHint=false while the text says "snapshot," the description should clarify what calling it actually does (single tick vs. ongoing subscription) and when it is the right choice.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. No misleading parameter claims are made.

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?

"Current planetary positions snapshot" names a concrete resource (planetary positions) and a concrete mode (current snapshot), which is enough to distinguish it from event-style stream siblings like astroway_stream_ingress or astroway_stream_lunar_phase. It stops short of explicitly contrasting itself with non-streaming ephemeris/position tools, so an agent must infer the difference.

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?

No statement of when to use this versus alternatives such as astroway_western_ephemeris or other astroway_stream_* endpoints, and no exclusions or prerequisites. The only usage signal is the implicit cadence from "tickSeconds=30"; the agent is left to infer the streaming use case from the group tag.

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