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

With no annotations, the description carries the full burden and delivers: it enumerates exactly what is destroyed (named graphs, delta graphs, registry entries, RDF manifest, members, access rules, search entries, SynthScholar reviews), describes deep-first cascade over all subspaces, notes provenance invalidation, and gives concrete failure semantics (403 for non-SuperAdmin, 502 partial-failure message and retry safety). This is exceptional disclosure for a destructive operation.

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?

Front-loads the highest-stakes facts (PERMANENTLY, SuperAdmin, irreversible) before the granular destruction list. Despite its length, every sentence carries unique operational information — cascade order, provenance, param constraint, pre-call guidance, error behavior — with no filler.

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 no output schema, the description still names the return signal (`subspaces_deleted`) and describes failure/timeout outcomes. For a high-risk deletion tool with two required params, it covers authorization, blast radius, prerequisites, and recovery — everything an agent needs to call it safely.

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 0%, so the description must compensate. It explains the confirmation mechanism ('confirm_slug must equal slug'), giving real semantic value for the second parameter. The primary 'slug' is left implicit but is self-evident from context, leaving a minor gap in an otherwise well-covered pair.

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 specific verb and resource with scope: 'PERMANENTLY delete a space and everything in it,' plus the SuperAdmin-only and irreversible qualifiers up front. This clearly distinguishes it from siblings like brainkb_create_space or brainkb_discard_upload. An agent knows exactly what the tool does without opening the schema.

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?

Explicit when-to-use with prerequisites and an alternative: 'Before calling: show the user the space AND its subspaces (brainkb_space_tree)... get their explicit confirmation.' It names the sibling brainkb_space_tree and forbids autonomous invocation ('Never call it to tidy up on your own initiative'). Nothing is left to inference.

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