get_castable_columns

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

With no annotations provided, the description carries the burden of disclosure and does well by revealing that a missing table returns a structured not_found with two common causes instead of a raw HTTP error. This adds meaningful behavioral context beyond the schema. It does not mention permissions or side effects, but as a read-only metadata getter, the disclosed error behavior is the key non-obvious trait.

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 exactly two sentences: the first states the tool's purpose, and the second adds essential error-handling behavior. There is zero waste, front-loaded purpose, and every sentence contributes new information. This is exemplary conciseness.

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?

Given the tool's moderate complexity (4 params, output schema present), the description covers the core purpose and a key edge case (missing table). The output schema handles return-value documentation. It lacks guidance on prerequisites or alternative use cases, but for a metadata getter, this is nearly complete. A small improvement would be to mention the limit default behavior, though it's in the schema.

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 100%, so all parameters (server_id, caslib_name, table_name, limit) are already described in the schema. The description adds no extra parameter-level semantics beyond what the schema provides, meeting the baseline for high schema coverage. The mention of 'names, types, labels, formats' refers to output, not parameters.

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 retrieves column metadata (names, types, labels, formats) for a CAS table, using a specific verb and resource. It distinguishes itself from related tools like get_castable_info (table metadata) and list_compute_columns (compute table columns) by focusing on column-level metadata for CAS tables.

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 implies usage when column metadata is needed but does not explicitly compare with alternatives or state when not to use it. Sibling tools suggest related metadata functions, but the description lacks explicit guidance on choosing this tool over get_castable_info or list_compute_columns. The context is clear enough for a user already aware of CAS concepts, but exclusions are absent.

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