cas_unload_table

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

Beyond the annotations it discloses the key behavioral facts: the operation is table.dropTable on the session table, the source data is unchanged, and promoted/global tables are rejected rather than dropped. That is meaningful context for a mutating-sounding call whose destructiveHint is false; the only gap is error/return behavior.

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?

Two tight sentences with the operation front-loaded and the safety caveats second; nothing is redundant. The parenthetical 'table.dropTable of the session table' is slightly jargon-dense but earns its place by pinning the exact semantics.

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 three-parameter, annotation-light tool with no output schema, the description covers the important safety nuance (source untouched, global tables refused) but omits parameter meaning and what the call returns or how failure surfaces. Adequate but with clear gaps an agent would hit at invocation time.

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% across three parameters, so the description must carry the burden and does not. It hints that 'table' refers to a session-loaded table, but says nothing about 'caslib' (required, and clearly the caslib that scopes the session table) or the optional 'connection' parameter.

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 ('Unload a table this CAS session loaded') and scopes it to the session, which implicitly separates it from siblings like cas_load_table and cas_session_loads. It does not name those siblings explicitly, so an agent must infer the pairing, but the operation is 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?

The description gives one clear exclusion ('A global (promoted) table is refused, never dropped'), which tells the agent when the call will fail. However, it never routes the agent to alternatives such as cas_session_loads (to see what is loaded) or cas_reload_tables, leaving the when-to-use decision only implied.

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