create

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

With no annotations present, the description carries the transparency burden. It discloses useful behavioral details: payload shape varies by resource, and "terms without aiMetadata will not be touched." However, it does not address response shape, validation behavior, idempotency, or side effects beyond the creation itself.

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 compact and front-loaded: the first sentence states the purpose, the second flags the resource-dependent payload, and the final sentences carry the critical AI metadata rule. Every sentence earns its place, and the text remains proportionate even though the underlying schema is enormous.

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 of this complexity, with no annotations, no output schema, and a massive conditional input schema, the description is minimal. It captures the dominant mainTerm/terms pattern and AI metadata obligation, but it does not guide the agent through simpler payload resources (e.g., name-only tools/formats/statuses) or mention fetching reference IDs via sibling tools. It is adequate but incomplete.

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?

Top-level schema description coverage is 0%, so the description must compensate. It adds real meaning by explaining that payload structure is resource-dependent, that term-bearing entities require mainTerm plus optional terms with correct IDs/types, and that aiMetadata fields are required for AI-generated content. It does not enumerate per-resource required fields, but it points the agent in the right direction.

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 action and target: "Create an entity for the given resource," and it names concrete resource examples (departments, professions, languages). It clearly conveys what the tool does, but it does not explicitly distinguish itself from the sibling create_term, so it lacks full sibling differentiation.

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 gives clear contexts for use: creating an entity for any supported resource, constructing term-bearing payloads with mainTerm and optional terms, and mandatory aiMetadata when generating AI content. Conditional guidance is explicit (“When creating AI-generated content, ALWAYS include”), though it does not mention alternatives or when-not-to-use cases.

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