create_inventionCreates a new invention disclosure in the user's Lightbringer organisation from a structured payload matching the invention template, and returns the created invention.
| Name | Required | Description | Default |
|---|---|---|---|
| definition | Yes | Complete validated V1 invention definition matching the advertised field structure |
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| url | Yes | ||
| refNum | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that this is a create operation, that the new disclosure is scoped to the user's organisation, and that the created invention is returned. It does not go beyond the annotations to discuss side effects, idempotency, or failure behavior, which is a notable but not critical gap for a simple creation tool with rich schema coverage.
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 a single, front-loaded sentence with no redundant wording. It conveys the action, target, scope, input constraint, and return value concisely, with the most important verb ('Creates') placed first.
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?
Given the very complex nested schema and the surrounding sibling workflow involving get_invention_template, validate_invention, and submit_invention, the description is adequate but not comprehensive. It does not mention the creation workflow or relationships to these siblings, but the output schema, annotations, and full parameter coverage compensate for much of that brevity.
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 coverage is 100% and the sole parameter, 'definition', already has a detailed description as a 'Complete validated V1 invention definition matching the advertised field structure'. The tool description adds the useful notion of 'matching the invention template', but this does not substantially deepen the semantic meaning beyond what the schema already provides.
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 identifies the operation (creates), the resource (new invention disclosure), the scope (the user's Lightbringer organisation), the input source (structured payload matching the invention template), and the return value (the created invention). This distinguishes it from siblings like get_invention, update_invention, and submit_invention without requiring the schema.
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 context for when to use the tool: creating a new invention disclosure from a template-matching payload. It does not explicitly compare against alternatives or state preconditions such as fetching the template first or validating the payload, but the intended use is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most invention lifecycle tools are clearly distinct, but there are overlapping pairs: add_comment and reply_to_comment both handle replies to threads, and fetch overlaps with get_invention for invention content. These overlaps require careful reading of descriptions to select the right tool.
Tool names generally follow a snake_case verb_noun pattern like list_inventions, create_invention, and update_invention. A few deviations such as fetch, search, and whoami break the pattern slightly, but the naming remains predictable overall.
At 18 tools, the set is slightly above the ideal scoped range and contains some functional overlap, making it feel heavier than necessary. Each tool has a plausible purpose, but the surface could be tightened by merging the overlapping comment and document-retrieval tools.
The tool set covers the core invention lifecycle well: create, get, list, update, validate, submit, and analyze, plus review and comment workflows. Minor gaps exist around comment management and lack of explicit review creation/deletion, but there are no major dead ends for common workflows.