create_reference

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently explains the auto-creation of FK columns when parent_columns/child_columns are omitted, mentions the default update_key=true, gives cardinality examples, and notes dry_run support. This goes beyond a simple 'creates a reference' and reveals meaningful side effects and options.

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 three sentences, each earning its place. The first sentence states the core purpose, the second explains the auto-creation behavior, and the third covers cardinality and dry_run. It is front-loaded with the most critical information and contains no fluff.

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 11 parameters, no annotations, and no output schema, the description covers the essential behavioral aspects: relationship type, auto-creation logic, cardinality, and dry_run. It does not describe return values or error handling, and it omits some parameter details, but it provides enough for an agent to make a correct primary call. It is not exhaustive but is reasonably complete for the core use case.

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. It adds meaning for several key parameters: parent_columns/child_columns (omission behavior), cardinality (examples), dry_run (support), and update_key (default true). However, it does not explain model_id, parent_table, child_table, code, name, or comment, though these are partially self-explanatory. The description provides partial but not comprehensive parameter semantics.

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 clearly states the tool's action: 'Create a foreign-key reference between two PDM tables (1:N from parent to child).' It specifies the verb, resource, and relationship type, making it distinct from sibling tools like update_reference, delete_reference, and list_references. The direction (parent to child) and cardinality are also clarified.

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 provides clear context on when to use this tool—to create a reference—and implicitly distinguishes it from updating or deleting references. It explains the auto-creation behavior when columns are omitted, which is a key usage condition. However, it does not explicitly name alternative tools or provide exclusion criteria, so it stops short of a 5.

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