list_inventionsLists the invention disclosures in the user's Lightbringer organisation, each with a title, reference number, and web link. Accepts an optional free-text query to filter results.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Free-text filter on title/reference |
| Name | Required | Description | Default |
|---|---|---|---|
| inventions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds scoping context (user's Lightbringer organisation) and return content, but does not describe behavior such as pagination, ordering, or authorization beyond that.
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?
Two focused sentences: the first states the core listing behavior and output content, the second covers the only option. No filler or redundant explanation.
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 simple read-only list with an optional filter, an output schema, and full parameter coverage, the description is largely sufficient. It could add an explicit pointer to sibling tools for single-invention lookups, but that belongs more to usage guidance and is not required to call this tool correctly.
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?
There is only one optional parameter, and the input schema already documents it fully as a free-text filter on title/reference. The description's mention of an optional free-text query adds no semantic information beyond the schema, so the baseline of 3 applies.
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 identifies a specific operation ('Lists the invention disclosures'), the scope ('in the user's Lightbringer organisation'), and the expected item fields (title, reference number, web link). This clearly distinguishes it from sibling tools like get_invention or create_invention.
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?
It is clear this tool is for browsing/listing invention disclosures within the user's org, and the optional query parameter is described as a filter. It does not explicitly name alternatives such as get_invention or search for single-item or broader queries, 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.
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.