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

Adds substantial context beyond the annotations: default publishing behavior, the draft escape hatch, the duplicate-fragmentation risk, and that the response includes the assigned ID and the caller's permissions. It does not mention permission requirements for creation or versioning/validity behavior, but the safety-relevant traits are well covered.

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-loaded with the core definition, then short paragraphs for scope exclusions, the completeness heuristic, the duplicate warning, the draft default and the return value. Nothing is redundant, though the incomplete-topic advisory is somewhat tangential to the creation call itself.

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?

With no output schema, the description usefully states what is returned (the topic with its ID and permissions). For an 8-parameter create tool it could say more about classification and references, but the essentials an agent needs to create a correctly placed, correctly published topic are present.

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 only 13%, yet the description only explains draft, label and parent implicitly, leaving classification, references, validFrom and validUntil completely undiscussed. The draft explanation does add genuine meaning beyond the schema, but four of eight parameters get no guidance anywhere.

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 ('Create a new topic in the workspace') and immediately characterizes what a topic is ('a reusable idea, entity, or domain node'), with examples of the named things it covers. It explicitly distinguishes itself from the sibling create_goal, create_gap and create_constraint tools.

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 both sides of the routing decision: use this for named entities, use the other create tools for goals, gaps and constraints. It also prescribes a pre-flight check ('Use engramic_topic to browse children at the intended parent') and explains when to set draft instead of the default publish.

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