create_graph

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

With no annotations, the description carries the full burden and does reasonably well: it discloses that omitting package produces an unsaved new package, and that width/height are Designer-only and do not persist into the exported .sbsar. It still omits what is returned (a graph handle/id), whether the graph is persisted, and any auth or application-state requirements.

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 description is short and front-loads the primary action plus the package caveat, then tacks on parameter notes. The sentences are terse, though the width/height note is split awkwardly and the format value list is dumped without framing.

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 5-parameter creation tool with no annotations and no output schema, the description covers most parameter semantics but says nothing about the return value (the caller likely needs a graph identifier to chain into create_node/connect_nodes) and nothing about required application state.

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 0%, so the description must compensate, and it explains width/height (Designer canvas size in powers of 2, re-specified at render time) and enumerates the four format values, plus the null-package behaviour. The required 'name' parameter is left entirely unexplained, which is the main gap.

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 description opens with a specific verb+resource ('Crea un grafo de composicion y lo abre'), and the note about the package parameter distinguishes a create-new-package case from adding to an existing one. It does not explicitly name open_graph as the alternative for existing graphs, so sibling differentiation is only implicit.

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?

Usage is implied by the creation semantics and the package behaviour, and it usefully routes the agent to render_outputs when width/height matter at render time. There is no explicit statement of when not to use this tool (e.g. to open an existing graph, use open_graph) or of prerequisites such as an active Designer session.

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