Each tool has a description covering what it does, when to use it, and side effects

A tool's description is the only text an AI reads when deciding whether to call it, and when to choose it over a similar tool. A description that just repeats the name ("Deletes a file" for a tool named delete_file) adds zero signal. Missing side-effect disclosures are especially dangerous: OWASP LLM09 surfaces here when the model cannot distinguish a read-only inspection tool from one that permanently deletes records, potentially auto-approving destructive calls without user confirmation.

Rewrite every description to answer three questions in one sentence: what it does, when to prefer it over similar tools, and whether it has side effects.

// src/tools/files.ts
server.tool(
  'delete_file',
  'Permanently delete a file from disk — irreversible, not sent to trash. ' +
  'Call read_file first to verify content. Use only when the user explicitly confirms deletion.',
  { path: z.string().describe('Absolute path to the file to delete') },
  async ({ path }) => { /* handler */ }
)

For tools that overlap (e.g., query_db and run_sql), add a disambiguation clause: "Use this for read-only SELECT queries; use run_sql for mutations."