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

Annotations already declare a non-read-only, non-destructive, non-idempotent write, and the description layers on substantive behavior beyond them: the model is a schema not data, layout is automatic, a link is returned, new names are normalized to Neo4j conventions while explicitly edited names are left unchanged, duplicate label sets are rejected, and every relationship is directional. Those normalization and rejection rules are exactly the surprises an agent would otherwise hit.

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?

The core action, its return value, and the guide prerequisite are front-loaded, and most later sentences carry operational rules an agent needs. It is long, though, and the naming-convention and caption guidance reads like reference documentation that could be trimmed or moved to the guide it already mandates.

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 five-parameter, deeply nested mutation with no output schema, the definition covers the important unknowns: what the return value is, the mandatory guide step, naming normalization, label-set uniqueness, caption ordering, and when to omit examples. Remaining gaps are minor, such as what happens on validation failure or whether repeated calls accumulate models.

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 40%, so the description has to compensate, and it does contribute real meaning: refs are self-chosen handles reused in relationships and notes, properties are in display order and the first node property's example becomes the caption, and examples should be omitted unless realistic. The naming-convention rules (PascalCase labels, UPPER_SNAKE_CASE types, camelCase keys, preserved capital runs) explain how input values are transformed, which no schema field communicates.

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 opening sentence names a specific verb and resource ('Creates a new graph data model'), states its inputs (nodes, relationships, notes), notes it auto-lays-out the model, and says it returns a shareable link. It also states what the model represents (a Neo4j schema, not instance data), which cleanly separates it from edit_model/get_model without ambiguity.

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?

It gives explicit prerequisites and post-conditions: 'Read get_modeling_guide first and pass its guideCode' and 'Always share the link with the user.' What it does not do is explicitly route between create_model and edit_model (e.g. 'use edit_model to change an existing model'), so an agent must infer the create-vs-edit choice from the name alone.

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