Stage CASDA products to Pawsey

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

Beyond annotations (readOnlyHint=false, idempotentHint=false), the description adds critical behavioral details: the tool submits a job (side effect), requires human-in-the-loop for terms acceptance, and returns human_gate_warnings. It also notes that results are Pawsey-network restricted, which is not captured by annotations.

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 relatively concise (3 sentences) and front-loaded with the main action. However, it packs several details (authentication, flag, sibling distinction, human confirmation, response hints) which could be more structured. Still, every sentence adds necessary information.

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?

The description covers the essential aspects: what the tool does, prerequisites (auth, flag), differentiation from a sibling, and a key behavioral constraint (human confirmation). It mentions the response includes human_gate_warnings, and given an output schema exists, it does not need to detail return values further. A slight gap is not mentioning the output schema structure, but that's acceptable.

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 input schema has 100% description coverage, so the baseline is 3. The description adds value by stating that empty input is rejected and duplicates are removed for product_ids, and that a UUID is generated if idempotency_key is omitted. This goes beyond the schema's descriptions.

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 clearly states the tool submits a Pawsey pull staging job via DataLink pawsey_async_service, specifying the verb 'submit' and the resource 'one Pawsey pull staging job'. It explicitly distinguishes from casda_stage_products by noting the network restriction, ensuring no confusion with siblings.

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 provides explicit when-to-use guidance: it requires authentication and the CASDA_ENABLE_STAGING flag. It also explains when not to use it (for general staging, use casda_stage_products) and mentions that licence/HPC confirmation must be done by a human, never auto-accepted. This gives clear context for agent decision-making.

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