create_record

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the write semantics are known. The description still adds real context beyond them: an authorization/enablement prerequisite and the duplicate-creation hazard from non-unique names, which an agent cannot infer from the schema. It stops short of saying what happens on validation failure or partial relationship resolution.

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?

Three short sentences with no filler, and the highest-value routing information (prefer create_log) is front-loaded in sentence two. Every sentence carries an actionable constraint.

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 4-parameter, non-idempotent mutation with full schema coverage, full annotations and an output schema, the description supplies the prerequisite, the sibling routing and the duplication hazard. Slightly incomplete only on failure behavior and whether relationship targets must pre-exist.

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% — entity_type enumerates valid values, bundle and attributes carry examples, and relationships documents its shape — so the schema does the heavy lifting. The description adds no parameter-level guidance beyond the general duplication warning, which matches the baseline 3.

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 any record') and names the sibling it should be preferred over ('Prefer create_log for logs with quantities'), so the agent can distinguish it. The word 'record' stays generic — the actual entity types live in the schema — keeping it just short of a 5.

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 an explicit alternative and the condition that selects it ('Prefer create_log for logs with quantities'), a pre-call workflow rule ('search first to avoid duplicates' because names are not unique), and a hard prerequisite ('Requires writes to be enabled'). When-to-use, when-not-to-use and alternatives are all covered.

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