Lightbringer

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

Annotations only indicate readOnlyHint=false and destructiveHint=false. The description goes further by disclosing that it returns the created comment, that ambiguous or missing quoted passages produce a response with candidate passages, and that anchoring within an existing thread creates a reply. This adds meaningful behavioral context beyond the annotations.

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 three focused sentences with no filler. The core action is front-loaded, followed by return behavior, error/ambiguity handling, and thread semantics. Every sentence contributes useful information.

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 moderately complex tool, the description covers the main action, return value, failure mode, and thread behavior. The schema fully documents parameters, the output schema exists, and annotations cover safety hints, so nothing essential is missing for an agent to invoke the 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?

The input schema already covers all parameters with 100% description coverage, so the baseline is 3. The description adds some context about quoted_text being anchored in the review markdown and ambiguity handling, but it does not materially improve understanding of the parameters 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 states the action ('Adds a comment'), the resource ('the document under review'), and the anchoring mechanism ('quoted passage of the review markdown'). It also distinguishes itself by noting that anchoring within an existing thread makes the comment a reply, which separates it from the sibling reply_to_comment tool.

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 useful context about when the tool is appropriate—adding anchored comments and handling ambiguous quotes—and notes reply behavior for existing threads. However, it does not explicitly tell an agent when to choose add_comment over the sibling reply_to_comment, nor does it state any exclusion criteria or alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying the possible states, that progress is included, and that findings only appear once the task has succeeded. It goes beyond the annotation baseline.

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 sentence that front-loads the verb and resource, then packs the key return fields and state enum into a compact list. Every word earns its place, with no repetition or filler.

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?

With one parameter, an existing output schema, and annotations covering the read-only/non-destructive nature, the description sufficiently covers what the agent needs to invoke the tool correctly. It even explains the lifecycle aspects (states and when findings appear), making it fully self-contained.

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%, and the only parameter 'ticket' is already described as 'The task ticket identifier'. The tool description repeats this concept but adds no additional semantic detail, such as the ticket format or how to obtain it. The high schema coverage justifies the baseline score of 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?

The description states a specific verb ('Returns') and a specific resource ('status of a long-running Lightbringer task identified by a ticket'), and enumerates the exact fields returned (state, progress, findings). This clearly differentiates it from sibling tools that deal with inventions, reviews, and comments.

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 clearly implies when to use this tool: after initiating a long-running task, to poll its status via the ticket. It doesn't explicitly name alternatives or exclusions, but none are apparent among the sibling tools, which are about different resource types. The context is clear enough without explicit exclusions.

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

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.

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

The annotations already establish readOnlyHint=true and destructiveHint=false, and the description adds the useful behavioral detail that this returns full content rather than metadata or a summary. It does not describe error behavior or auth requirements, but the annotations carry the safety profile.

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?

One sentence with no filler; the key action and resource are front-loaded, and the parameter is immediately implied by the ID reference.

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 read-only fetch with a full output schema and safety annotations, the description supplies the necessary domain context. It only lacks an explicit pointer to sibling contrast tools, which is more of a usage-guidance gap.

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 for the single id parameter is 100%, and the description confirms the id identifies the document to fetch. The description adds no format, source, or validation detail 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 states a specific verb ('Returns the full content of a single document') and names its resource types, so an agent knows what it does. It does not explicitly differentiate itself from sibling retrieval tools like get_invention or get_review, so it falls 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?

Usage is implied: call this when you have a document ID and need the full content. There is no explicit when-not-to-use guidance or naming of an alternative such as search or get_invention.

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

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

Annotations already declare readOnlyHint and destructiveHint, covering safety. The description adds the behavioral detail of returning markdown and specific content, but does not elaborate on potential side effects or response format beyond that. Since annotations are present, this additional info is sufficient but not extensive.

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, concise sentence that front-loads the action and clearly states the output format and contents. There is no unnecessary verbosity or ambiguity.

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?

The description sufficiently conveys the purpose and expected return content. Although an output schema is not provided, the markdown format and listed sections give adequate context for an agent to understand the result. It is complete for a simple read operation.

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?

The schema already defines invention_id as a required string with a minimal description. The tool description does not add any additional meaning or elaboration about the identifier (e.g., where to find it, expected format). With full schema coverage, no extra value is provided, so a baseline score of 3 is appropriate.

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 states the tool returns an invention disclosure in markdown format, listing the included sections. It is specific and distinct from sibling tools like list_inventions or get_invention_template by focusing on a single disclosure with its content.

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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., list_inventions to obtain IDs, or get_invention_template for a template). It lacks conditions or exclusions, leaving the agent to infer usage from the parameter name.

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

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

The description discloses the asynchronous nature of the operation: it may take seconds to minutes, returns a pending status while running, and includes ticket identifiers that allow later retrieval of results. This goes well beyond the sparse annotations and helps the agent handle the full lifecycle.

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 sentences, with the core action and resource in the first sentence and the important async caveat in the second. No filler or redundancy.

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 with only two parameters, a full output schema, and no destructive safety concerns, the description covers everything necessary to invoke it correctly and interpret a pending response. The ticket-identifier mention makes the asynchronous flow actionable, even though it does not name the exact retrieval sibling.

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% and both parameters already have descriptions, so the baseline is 3. The description adds mild value by expanding the 'problem' enum to 'problem framing' and clarifying that invention_id refers to an invention disclosure, but it does not supply any syntax or additional parameter-level details.

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 opens with a specific verb and resource: 'Runs Lightbringer's patent-analysis suite on an invention disclosure.' It also names the output type (structured findings) and the selectable focus areas, which clearly distinguishes it from simpler retrieval/validation siblings like get_invention or validate_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?

The intended use case—wanting patent-analysis feedback on an invention disclosure—is clear from the description, but there is no explicit when-to-use/when-not-to-use guidance or reference to alternative tools such as validate_invention, get_review, or check_task_status for handling pending results.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable context beyond annotations by specifying what the template includes and that it provides capture guidance before drafting, giving the agent a clear expectation of the returned content. No contradiction with annotations.

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, information-dense sentence that front-loads the core purpose and then expands with relevant details. Every clause contributes meaning—schema, per-field guidance, structure, and capture guidance—without redundancy or filler.

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?

With no parameters, a read-only annotation, and an output schema present, the description sufficiently explains what the tool does and what the template contains. An agent can select and call this tool without missing critical information; the only minor gap, explicit usage vs. alternatives, is not essential for a simple getter.

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 are zero parameters, so the baseline is 4 under the rubric; the description correctly avoids inventing parameter details. The description's content about what the template returns also helps the agent understand what the empty-input call will yield.

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 opens with a specific verb-resource pair, 'Returns the current invention authoring template,' and explicitly enumerates the template's contents: schema, per-field guidance, structure, and capture guidance. This clearly distinguishes it from siblings like get_invention (which returns an invention) and create_invention (which creates one).

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 'used to create a new invention' implies the intended use case, but there is no explicit statement of when to choose this tool over alternatives, nor any mention of when not to use it. Sibling differentiation is left to inference from the name and content.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds useful behavioral details beyond that: the document is rendered as markdown, comment IDs are stable, and attorney redlines come as structured suggested changes. It does not mention error cases or prerequisites, but none are critical for a simple read operation.

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 focused sentence that front-loads the main verb and resource, then uses a colon to list the included elements. Every clause adds value, and there is no repetition or filler.

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 single-parameter, read-only retrieval tool with an output schema and sibling list_reviews, the description is complete: it states exactly what is returned, including markdown rendering, stable comment IDs, and redline semantics. No critical operational detail is missing.

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 parameter, review_id, and the schema description covers it 100%, so the baseline is 3. The description does not add further parameter-level meaning such as how to obtain the review_id or expected format, but the schema's field name is self-explanatory.

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 opens with a specific verb and resource, 'Returns a review', then enumerates the concrete payload pieces: metadata, markdown rendering of the document, comment threads with stable IDs, and attorney redlines as suggested changes. This makes it easy to distinguish from sibling tools like list_reviews or get_invention_feedback.

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 implies this tool is for retrieving one full review with comments and redlines, but it never explicitly states when to prefer it over alternatives such as list_reviews or respond_to_review. There is no exclusionary guidance, so the agent must infer usage from the singular 'a review' and the detailed return contents.

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

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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable detail about the response content (status, user response status, awaited participants, etc.) beyond those flags. It does not contradict annotations and gives a fuller picture of what a successful call returns.

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, fairly dense sentence that front-loads the core action ('Lists reviews...') and packs in the relevant details. It is efficient, though slightly long; still, every clause adds information, earning a 4.

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 that the tool has an output schema (indicated by context signals), the description sufficiently covers the purpose and returned scope without needing to spell out return values. It does not address pagination or sorting, but those are likely handled by the output schema or are minor for a listing tool. Overall complete for an agent to invoke it 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?

The sole parameter 'status' is fully described in the schema (enum open/closed). The description does not add any additional meaning or constraints beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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?

Clearly states it lists reviews for a user (participant or creator) and enumerates the included details (status, response status, awaited participants, title/reference, and invention for report reviews). It implicitly distinguishes from the single-review sibling get_review by using the plural 'list' and listing multiple returned attributes.

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?

Provides context that the user must be a participant or creator, but does not explicitly mention when to use this vs. alternatives like get_review, nor does it note exclusions (e.g., not for admin viewing all reviews). The usage is implied but not explicit.

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

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

Annotations already indicate this is a write operation that is not read-only and not destructive. The description adds the return behavior and the precondition that the thread must already exist, but does not disclose notification side effects, permissions, or failure behavior. It does not contradict the annotations.

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 states the action, the target resource, the key identifier, and the return value 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?

With a well-populated input schema, an output schema, and annotations, the description is largely sufficient for a straightforward reply operation. The only notable gap is the absence of guidance on when to choose this tool over sibling tools, but this is a minor omission for a simple write operation.

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%, so the schema already documents comment, review_id, comment_id, and target_user_ids. The description adds no parameter-level detail beyond what the schema provides, so the baseline score 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 clearly states a specific action and resource: 'Adds a reply to an existing comment thread identified by its comment ID, and returns the created reply.' This distinguishes it from broadly creating comments or responding to reviews, though it does not explicitly name sibling tools.

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 'existing comment thread identified by its comment ID' implies this tool should be used when replying to an already-created thread, but the description does not explicitly contrast it with alternatives like add_comment or respond_to_review. Usage context is implied rather than stated.

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

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

Annotations already mark this as a write operation, and the description adds that it records the response and returns the updated review state. It is consistent with the annotations and gives useful behavioral context without overstating side effects.

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 filler. It states the action, the object, and the return behavior in a compact form.

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 small tool with full parameter schema coverage, annotations, and an output schema, the description supplies the essential purpose and return behavior. It is missing only explicit guidance about which sibling to prefer, but nothing critical for invoking it correctly is absent.

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%, so the description does not need to redefine parameters. It adds no extra semantic detail about review_id, response, or message beyond what the input 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 names a concrete action ('Records'), a specific resource ('user's response to a review'), and the outcome ('returns the updated review state'). It is clearly about responding to a review, though it does not explicitly differentiate itself from sibling tools such as add_comment or reply_to_comment.

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 use case is implied by the phrase 'response to a review' and by the approve/request_changes enum in the schema, but the description never states when to choose it over alternatives or when not to use it. No sibling tool is referenced.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds crucial behavior: asynchronous indexing means recent edits may not be searchable, and empty results are not proof of absence. It also discloses cursor-based pagination. No contradiction with annotations.

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 sentences with no fluff. Purpose is front-loaded, the pagination note is briefly stated, and the indexing caveat is essential yet concise. Every sentence adds value.

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?

With an output schema present, the return format is already covered, and the description adds operational details like pagination and indexing lag. However, it omits explanation of limit and category parameters, which are not described in the schema. This gap makes the definition adequate but not fully complete for an agent deciding how to scope a search.

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?

The schema covers query and cursor with descriptions (50% coverage). The description mentions cursor-based pagination, which adds context, but it does not explain the limit bounds or the category enum meanings. The description only partially compensates for the missing schema descriptions of limit and category.

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 states it searches Lightbringer organisation documents (inventions, patent applications, reports) and specifies the return fields (ID, title, summary). This is a specific verb+resource scope that distinguishes it from sibling tools like get_invention (direct fetch) and list_inventions (enumeration).

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 implies usage for content-based search but does not explicitly explain when to use it versus alternatives (e.g., 'use get_invention when you know the ID'). There are no when-not-to-use instructions or alternative routing, so the guidance remains implicit.

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

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

Beyond annotations, the description discloses meaningful behavioral and privacy context: reports land in an engineering channel reviewed by people and are not visible to the signed-in user. It also warns about confidential material, which helps the agent set user expectations. This adds real value over the minimal readOnly/openWorld/destructive hints.

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 sentences, each earning its place: the first defines the purpose, the second explains where the report goes and its visibility, and the third gives practical writing guidance. The description is compact and front-loaded, with no filler or repetition.

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?

The description covers what the tool does, when to use it, where the report goes, what happens to it, and how to write it responsibly. Combined with a fully described schema, annotations, and an output schema, nothing essential is missing for an agent to invoke it 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?

The input schema already documents all three parameters with full 100% coverage, including the category enum values and the feedback field's intent. The description reinforces the high-level, non-confidential framing for feedback content but does not add parameter-specific meaning beyond the schema. Per the calibration baseline, 3 is appropriate.

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 opens with a specific verb and resource: 'Sends a report about the Lightbringer tools themselves to the engineering team.' It then enumerates the report subtypes (broken or surprising behaviour, missing capabilities, friction), which clearly differentiates this from sibling tools like get_invention_feedback or add_comment. There is no ambiguity about what this tool does.

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 explicit trigger conditions: broken or surprising tool behaviour, missing capabilities, or friction encountered while working. It also provides content guidance for composing a good report. It does not explicitly name sibling alternatives or state when not to use the tool, but the purpose is narrow enough that the use cases are clear.

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

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.

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

The annotations already mark this as destructive, and the description adds meaningful behavior by explicitly saying it overwrites the specified sections and returns the updated invention. This clarifies that content is replaced rather than merged, which is valuable context beyond the structured annotations.

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 short sentences fully convey the operation, the overwrite behavior, and the return value. There is no filler or redundant restatement; each sentence earns its place.

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 nested-object update tool with an output schema and destructive annotations, the description is adequately complete. It explains the core behavior, and the schema covers detailed section properties, so nothing critical is missing for an agent to use it 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?

Schema description coverage is 100%, so the schema already documents each section parameter and the empty-string clearing behavior. The description adds a general statement about replacing section content, which aligns with the schema but does not meaningfully expand parameter semantics.

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 uses a specific verb and resource: it updates one or more sections of an existing invention disclosure. It also clarifies that this is an overwrite operation and returns the updated invention, cleanly distinguishing it from creation and retrieval siblings like create_invention and get_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?

The description clearly conveys that this tool is for modifying existing invention disclosures by replacing section content. It does not explicitly name alternatives or state when not to use it, but the 'existing' qualifier gives enough contextual guidance for an agent to avoid using it for creation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not restate safety. It adds specific behavior beyond annotations by specifying that validation is performed against the authoring schema and that the response contains errors and warnings, which clarifies what kind of read-only operation this is.

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 sentence states the action, target, and result without redundancy. It is front-loaded with the key verb and resource, making it easy for an agent to scan.

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 read-only validation tool with one parameter, a fully detailed schema, and an output schema present, the description is largely sufficient. It could be slightly more complete by explicitly saying to call it before submit_invention, but the schema and annotations carry most of the necessary context.

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 nested definition parameter is thoroughly described in the schema itself, so the description does not need to document fields. The description merely calls the object a 'draft invention,' which aligns with the schema but adds no material semantic value beyond it.

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 uses a specific verb ('Validates') and a clearly defined resource ('a draft invention against the authoring schema'), and names the result (errors and warnings). It is clearly distinct from creation, retrieval, and submission siblings, but it does not explicitly name or contrast any alternative tool, so it stops 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?

The phrase 'draft invention' implies this is a pre-submission/pre-publication check, and the validation-against-schema wording implies it is for compliance checking. However, the description gives no explicit when-to-use or when-not-to-use guidance and names no alternative tools such as submit_invention or create_invention.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns the user and organisation, but does not describe edge-case behavior (e.g., if the connection is unauthenticated). Since annotations cover the main trait, a 3 is appropriate.

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, direct sentence that states exactly what the tool does with no filler. It is front-loaded with the action and result, making it easy to scan.

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?

The output schema exists to define the return format, and the description names the two key pieces of information (user and organisation). For a zero-parameter, read-only tool, nothing essential is missing.

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?

This tool has zero parameters, so the input schema is trivially complete. The baseline of 4 applies because no parameter documentation is needed; the description adds no param info, but none is required.

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 states the verb ('Returns') and the resource ('the signed-in Lightbringer user and organisation'), distinguishing it from sibling tools. It precisely identifies what the tool provides without ambiguity.

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?

While no explicit when-to-use guidance is given, there are no sibling tools offering comparable functionality, so the implicit use case is obvious. A brief note on typical usage (e.g., 'call to verify identity before other operations') would elevate it, but the lack of alternatives makes the absence less critical.

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