compact_dataset

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

No annotations are provided, so the description carries the full burden and largely discharges it: it discloses asynchronous background execution with a task_status polling pattern, the space-reclamation side effect, and the fact that delete_old 'cannot be undone' and 'frees the most space.' Irreversibility of a destructive option is exactly the disclosure an agent needs.

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?

Four short, front-loaded sentences: purpose first, then execution model, then the consequential parameter, then the applicability constraint. No filler and no repetition of schema content.

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 an async mutation tool with no output schema, the description supplies the critical missing piece — that results must be obtained via task_status rather than a direct return — plus the irreversibility caveat and the TDB2 applicability limit. Nothing an agent needs to invoke it safely is absent.

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 the baseline is 3, but the description adds real meaning beyond the schema: delete_old's schema text only says 'Delete the pre-compaction copy. Default false,' while the description adds the consequence (frees the most space) and the risk (cannot be undone). The dataset parameter gets no added treatment, but it is self-explanatory and defaulted.

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?

Specific verb+resource ('Compact a TDB2 dataset') with an explicit effect qualifier ('reclaiming space held by superseded data'). The added scope constraint 'Only meaningful for TDB2 datasets' makes it unambiguous against siblings like backup_dataset or delete_dataset, none of which perform compaction.

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?

Gives concrete operational context — it 'Runs in the background; poll with task_status' — which tells the agent how to consume the result, and 'Only meaningful for TDB2 datasets' excludes invalid targets. It does not, however, state when compaction is warranted versus alternatives such as backup_dataset or a fresh write.

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