clients.records.archive

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

Excellently supplements annotations. While annotations flag destructiveHint=true, the description crucially clarifies this is a 'soft-delete' (not permanent data loss), explains the cascading visibility impact on linked projects/invoices/follow-ups, and notes idempotent behavior implied by timestamp-setting.

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 dense sentences with zero redundancy. Front-loaded with the core action (soft-delete mechanism), followed immediately by usage context and cascading effects. Every clause conveys distinct information about behavior or usage.

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 single-parameter archive operation, the description comprehensively covers the mechanism (timestamp setting), visibility semantics (hidden from normal queries), data persistence (auditable history), and relational impact (linked entities remain). No output schema exists, but the description adequately explains the state change.

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 has 100% description coverage for the single client_id parameter. The description text refers to 'a client' generally but does not add parameter-specific details (format hints, examples) beyond what the schema already provides, meeting the baseline for fully-documented schemas.

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 explicitly states 'Soft-delete a client by setting their archived_at timestamp,' providing a specific mechanism (soft-delete), resource (client), and differentiating it from siblings like 'update' or hard delete by emphasizing preservation of full history.

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?

Provides explicit when-to-use guidance ('when a freelancer is done working with a client and wants to retire the record') and explains consequences (hides from normal queries but preserves audit trail). Lacks explicit mention of alternative tools (e.g., 'use update instead for status changes'), but the use case context is clear.

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