workflow_archive

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

Annotations declare destructiveHint=true and openWorldHint=true, so the agent knows this is a mutating, network-bound operation; the description adds useful detail that it writes to a local SQLite database and supports incremental sync. But it never explains what the destructive flag means in practice—whether existing archived data is overwritten or merged, whether confirmation is required (the 'yes' param implies it), or that the run may be long due to remote fetching.

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?

Three tight sentences, front-loaded with the core action before the incremental/full variants. The trailing pointer to 'search' is efficient but references a command not present among siblings, slightly diluting the value of that sentence.

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 22 flags, no output schema, and destructive/open-world annotations, the description covers the essential 'what it does and how it differs across modes' story. It leaves out return-value shape and confirmation behavior, but for an archival command whose flags are fully in the schema, this is reasonably complete.

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 100%, so all 22 parameters are already documented, establishing the baseline of 3. The description reinforces the semantics of the 'full' flag (full resync vs incremental) but does not mention any parameter by name or clarify the interaction of 'agent', 'yes', 'dry-run', or 'data-source' with this command.

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 concrete verb and resource: fetch all syncable resources from the API and persist them into a local SQLite database. The incremental-vs-full distinction is spelled out. It does not, however, distinguish itself from close siblings like 'sync' and 'import', leaving the agent to infer which one performs the local archive.

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 a workflow (archive first, then use 'search' for full-text search), which is useful routing, but 'search' is not one of the actual sibling tools (the closest are 'sql' and 'goodreads-search_books'). No guidance is given on when to choose this over 'sync' or 'import', or on prerequisites such as authentication.

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