sas_run_status

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

Beyond the readOnlyHint annotation, the description discloses blocking semantics (waits up to wait_ms, capped at 25 s), the full set of return states (running, stopping, cancel_failed), what 'running' reports (elapsed time, waiting_for another tab's run), and the recommended recovery action when Viya fails to cancel. This is genuinely useful behavior an agent could not infer from the schema.

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?

It is compact and dense with value, but it is a single convoluted fragment with stacked parentheticals and opens with a noun phrase instead of the verb, so the key point is not cleanly front-loaded.

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 no output schema, the description carries the burden of explaining return values and does so thoroughly, including the waiting and post-stop states. It falls short only on error behavior for an unknown/expired run_id and on where to fetch the result rows.

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 coverage is 0%, so the description must compensate. It does explain wait_ms meaningfully (blocking duration with a 25 s cap) and implies run_id is the handle returned by sas_query/sas_execute, but it never states the default of 0 or what happens when wait_ms exceeds the cap.

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 identifies the resource precisely — the status/result of a background SAS run originated by sas_query / sas_execute — which distinguishes it from sas_rows or sas_stop. It never uses an explicit verb ('Returns the status of...'), reading as a sentence fragment, but the purpose is still unambiguous.

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?

It implies the call pattern (poll after launching sas_query/sas_execute, and poll after sas_stop returns 'stopping'), but never states when not to use it, how often to poll, or how it relates to sibling retrieval tools like sas_rows. Usage is inferable rather than guided.

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