Import Workflow

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

Since there are no annotations, the description carries the full behavioral burden and it carries it well: it discloses that import creates a new draft, that it returns issues alongside the id, and that it is deliberately lenient with a rationale ('refusing would lose the other forty nodes'). The main shortcoming is not detailing what the 'issues' look like or whether anything is partially written when problems occur.

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?

Two sentences, front-loaded purpose first and return value second. The leniency rationale ('refusing would lose the other forty nodes to fix one') is a slightly vivid metaphor but earns its place by explaining a surprising behavioral relaxation that would otherwise seem like a bug. No wasted structure.

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 tool with one required nested object and no output schema, the description covers the operation, the key behavior (lenient import), and the return essentials (workflow_id plus issues). However, it does not concretize the 'issues' payload or explain what happens if a conflicting workflow_id is supplied. It is adequate, not exhaustive, for a creation-related tool with three parameters and no annotations.

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 100%, and the schema already documents name, workflow, and workflow_id well. The description adds only the conceptual framing that the payload is a WorkflowSchema document imported into a new draft, which reflects the workflow parameter's meaning. This meets the baseline 3 but contributes no extra param semantics beyond the schema.

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 states a specific verb and resource: 'Read a WorkflowSchema document into a NEW draft' and gives the return value ('workflow_id, plus any issues found'). This clearly distinguishes import from list/get/delete, but it does not explicitly name the sibling it is not (e.g., create_workflow or export_workflow), so the differentiation is implied rather than explicit.

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?

The description explains when leniency applies ('a document referencing a kind this host has not registered still imports') and implies the tool is the import counterpart to export_workflow (whose schema is referenced in the parameter description). But it never explicitly says 'use this when...' or points to an alternative like validate_workflow for stricter checking, leaving the usage boundary to inference.

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