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

Annotations already declare non-destructive, non-read-only, non-open-world behavior, so the bar is lower, but the description still adds real value: default publication on creation, the duplicate-fragmentation risk, and the return shape (assigned ID plus caller permissions). It does not address the non-idempotent hint explicitly (e.g., what happens on repeat calls with the same label), nor permission/scope requirements for creating under a given parent.

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?

Organized into short, front-loaded paragraphs with the core purpose first, then per-parameter notes, then publishing behavior and return value. A few lines are near-duplicates of schema hints (subtype, detail), which is minor padding but not harmful.

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 10-parameter create tool with a nested references array and no output schema, the definition covers the creation model and return value but leaves the metadata surface (classification, validity window, references, parentId) largely undocumented. An agent could create a resource, but not confidently populate or explain half the fields.

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 10%, so the description must compensate and only partially does. It explains detail (shape depends on subtype), subtype (determines detail shape), status (defaults to active), and draft, but says nothing about label constraints, parentId semantics (only a schema hint covers it), classification levels, validFrom/validUntil, or the references array of rel/url pairs — six of ten parameters remain unexplained.

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 resource in the workspace") and defines what a resource is ("structured, reusable asset whose shape is determined by its subtype"), with example uses. It does not explicitly distinguish itself from create-side siblings such as engramic_create_concept, create_goal, create_gap, or create_constraint, so the boundary is inferred rather than named.

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 concrete usage examples (brand kits, templates, credentials) and an explicit pre-step: "Use engramic_topic to browse children at the intended parent first — duplicates fragment the graph." It also clarifies the publish-vs-draft decision. It stops short of saying when to choose this over other create_* tools or update_resource.

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