table_manage

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions one trait: 'resume' is 'Token-efficient', but does not describe side effects for destructive operations like delete or remove_column. There is no mention of persistence, irreversibility, or permission requirements. The operation names are self-explanatory, but the description adds minimal behavioral context beyond what the names imply.

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 well-structured with sections for Operations, Args, and Examples. It is front-loaded with a summary line and uses bullet points for readability. While it is lengthy (about 30 lines), each section serves a purpose—operations, parameter mapping, and usage examples. No fluff, but it could be slightly more compact without losing clarity.

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 complexity (17 parameters, 9 operations), the description is quite complete: it covers all operations, parameter-operation mappings, and provides multiple examples. An output schema exists, so return values need not be described. It lacks edge-case guidance (e.g., what happens on invalid operation or missing required parameters), but for a dispatcher-like tool, it provides sufficient context for an agent to make initial calls.

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%, so the description must compensate. It does so effectively by listing each parameter and associating it with applicable operations (e.g., 'intent: [create] comparison / citation / summary', 'columns: [create] 欄位列表 [{...}]', 'limit: [preview] 預覽行數'). It also provides concrete examples. Not every parameter (e.g., offset, artifact_only) is explained, but the main ones are, and the format is clear.

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's purpose as a table management tool (建立、刪除、列表、預覽、渲染、Schema 演進) and enumerates nine distinct operations (create, delete, list, preview, resume, render, add_column, remove_column, rename_column). It provides specific verb-resource pairs and examples, which distinguishes it from sibling tools like table_data or plan_table that likely focus on specific operations.

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?

Usage is implied through the operation list and examples (e.g., 'table_manage("create", intent="comparison"...)' shows when to use create). However, there is no explicit guidance on when to use this tool versus alternatives like table_cite, table_data, or docx_table. It does not mention exclusions or alternative tools for specific scenarios, leaving the agent to infer applicability.

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