submit_inventionSubmits an invention disclosure for review within Lightbringer and returns its updated status.
| Name | Required | Description | Default |
|---|---|---|---|
| invention_id | Yes | The invention identifier |
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| url | Yes | ||
| refNum | No | ||
| submitted | Yes | ||
| alreadySubmitted | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool is non-read-only, idempotent, and destuctive, so the description does not need to repeat those flags. It adds context about the submission workflow and the returned status, but it does not explain what destructive side effects occur, such as whether the invention becomes locked or uneditable.
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?
A single front-loaded sentence with no filller. It states the action, the target resource, and the result efficiently.
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 one-parameter tool with a fully documented schema, output schema, and annotations, the description is mostly complete: it explains what the tool does and the return status. The main gaps are prerequisites and destructive side effects, but an agent can likely invoke it correctly for an existing invention without further detail.
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%; the single invention_id parameter is already described in the schema. The description does not add parameter-specific details beyond echoing the invention disclosure concept, so it meets the baseline but adds little.
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 names a specific verb (submits), a resource (invention disclosure), and a purpose (for review), while also stating that the tool returns the updated status. This clearly distinguishes it from siblings like create_invention and update_invention, which handle creation and editing rather than submission for review.
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 phrase 'submits an invention disclosure for review' implies the tool is used when an invention is ready for review, but it gives no explicit guidance on when to choose this over create_invention, update_invention, or validate_invention. No alternatives or exclusions are stated.
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.