Lightbringer

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

Adds real context beyond the annotations: it discloses the ambiguity fallback with candidate passages, the thread-reply redirect, and email/in-app mention notifications to targeted users. It does not explain why destructiveHint=true applies to what sounds like an additive comment, which is the one behavioral question left open.

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?

Four tight sentences, front-loaded with the core action before edge cases (ambiguity, threads, notifications). No filler, though the notification sentence could be trimmed slightly.

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?

An output schema exists, so return-value details are rightly omitted; instead the description covers the non-obvious edge cases an agent must anticipate (unresolvable anchors, threaded replies, notification side effects). Complete enough to call 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining what quoted_text actually does (anchors the comment) and clarifying that target_user_ids drive email and in-app mention notifications. It adds meaning rather than repeating the schema.

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?

States a specific verb and resource ('Adds a comment to the document under review') and pins down the anchoring mechanism (quoted passage of the review markdown). It does not explicitly distinguish itself from the very similar sibling add_discussion_comment, leaving sibling differentiation to inference.

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?

Implies when the tool applies by describing the threaded-reply behavior and the ambiguity response, but never states when to use this instead of add_discussion_comment, reply_to_comment, or respond_to_review. Usage is inferable but not spelled out.

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=false, destructiveHint=true, and openWorldHint=true, so the schema carries the safety profile. The description adds genuinely new behavioral context: audience visibility (review creator and all participants), a notification side effect (in-app and email to eligible participants), and that the updated discussion is returned. It does not state required permissions or explain the destructive annotation.

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, front-loaded with purpose, then disambiguation, then side effects. No filler and each sentence contributes distinct 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?

With an output schema present, return-value detail is optional, and annotations plus full schema coverage cover most remaining questions. The only mild gap is that commenting permissions/eligibility are referred to vaguely ('eligible review participants') without saying who qualifies.

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% for both parameters, so baseline 3 applies. The description explains the conceptual role of the comment (standalone, review-scoped) but adds no syntax, format, or constraint detail beyond what the schema already documents.

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?

States a specific verb and resource ('Posts a standalone comment to the review's discussion feed') and explicitly distinguishes itself from the sibling add_comment by noting it is 'not anchored to a passage of the document'. An agent can select this over add_comment without opening either 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?

Names the alternative (add_comment) and gives the discriminating condition: unanchored general remarks, questions, or status updates about the review as a whole. The routing decision is fully specified rather than inferred.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), and the description adds real context beyond them: validation occurs before saving, success returns the saved link and revision, and write access is required. Return details are partly redundant given the output schema, keeping this just short of a 5.

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?

Five short sentences, each carrying distinct information (what it creates, where to get guidance, validation/return behavior, follow-up path, permissions/publication boundary), with the core action front-loaded and no 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 create tool with an output schema, the description covers the remaining gaps: prerequisites, validation behavior, the pointer to the template for capture schema, and the separation of publication. An agent has everything needed to decide to call it and what to fetch first.

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 0% across two parameters (title, sections), so the description must compensate. It does so only indirectly by pointing to get_strategy_template for capture guidance and schema; it never explains title or the sections array/structure itself, leaving the agent to fetch another tool before it can build valid input.

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?

Specific verb+resource: 'Creates a populated draft strategy.' It also clarifies the object is a draft (not a published strategy) and names the related tools (get_strategy_template, edit_strategy), which separates it cleanly from siblings like edit_strategy and set_strategy_publication.

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?

Explicit routing: capture guidance/schema comes from get_strategy_template, refinement happens via edit_strategy, and 'Publication is separate' signals set_strategy_publication. It also states the prerequisite (strategy management rights, including customer moderators), giving the agent when-to-use and gating conditions.

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 destructiveHint=true and idempotentHint=true, so safety is partly covered. The description adds two pieces of context those annotations do not convey: the deletion is permanent/irreversible and it requires strategy management rights. It doesn't mention side effects on related data, but this is solid added value over the structured fields.

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, zero filler, with the destructive nature and the activation condition front-loaded before the permission requirement.

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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description covers the call condition, permanence, and auth requirement; the only minor omission is any note on cascading side effects for a destructive 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?

Only one parameter (strategy_id) and schema description coverage is 100%, so the schema fully documents it. The description adds no format or constraint detail beyond what the schema already provides, which is the baseline case.

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?

States a specific verb ('Permanently deletes') and resource ('a strategy'), making clear this is an irreversible destruction of a strategy rather than an edit or a task deletion as in delete_task. An agent can distinguish it from edit_strategy and delete_task without opening 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?

Gives an explicit usage condition ('when explicitly requested by the user'), which meaningfully constrains when the agent should invoke it. It does not name alternative tools or describe when-not-to-use beyond that, so it falls short of an explicit routing statement.

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?

With annotations already covering destructiveHint, idempotentHint, readOnlyHint, and openWorldHint, the description adds substantial value: what is permanently deleted (including cached findings), that it is available in any execution state, what side effects it does not have, and that repeated deletion returns not_found. This is rich 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?

Four short sentences, front-loaded with the core action and scope, followed by availability and important exclusions. Every sentence earns its place and there is no 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?

Given the presence of an output schema and rich annotations, the description is complete for a destructive delete operation. It covers scope, availability, side effects, non-effects, and idempotency behavior, leaving no critical gaps for correct invocation.

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 task_id is fully documented in the schema. The description adds useful scoping context (current user, connected organisation) but no syntax or format details beyond what the schema provides, so the 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 states a specific verb (permanently deletes) and resource (automated task) with scope (owned by the current user in the connected organisation) and includes cached findings. It clearly distinguishes from siblings like get_task_status or list_tasks, and clarifies it is not an innovation deletion.

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 gives clear contextual conditions: available in any execution state, and it lists things it does not do (cancel upstream analysis, delete the innovation, withdraw a service request). However, it does not explicitly name an alternative tool or say when to use one over the other, so it falls short of the top score.

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 destructive, non-idempotent, non-read-only, but the description adds substantial behavior beyond them: atomic batch semantics, no redlines, preservation of unchanged text and comment anchors, rejection of ambiguous matches, rejection of edits touching pending review changes, rejection of conflicting revisions, and the orphaned_discussion_ids side effect. This is exactly the extra context the annotations cannot carry.

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?

Front-loaded with the core action, then each following sentence adds a distinct behavioral fact (atomicity, redline-free application, anchor preservation, rejection rules, response side effect, permissions). 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?

An output schema exists, so return values need not be documented, yet the description still flags the notable orphaned_discussion_ids field. Combined with the rejection rules and permission requirement, an agent has everything needed to invoke this mutation safely.

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 only 33%, and the description compensates by explaining that 'revision' is the value returned by get_strategy and that operations are section edits applied as one batch. It does not enumerate the five action variants or their required fields, so it is not fully compensating for the coverage gap.

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?

Specific verb ('applies an atomic batch of section edits') plus resource (strategy sections) and the key scoping constraint that it operates on a revision from get_strategy. An agent can distinguish this from create_strategy, delete_strategy, and update_innovation without opening a 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?

Gives the precondition for use (revision from get_strategy) and the rights requirement, plus rejection conditions that tell the agent when the call will fail. It does not name a sibling alternative or explicitly state when to prefer another tool, 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 cover readOnly/non-destructive/closed-world, and the description still adds material context beyond them: the consent and organisation-membership requirements, and the security-relevant caveat that notes are user/agent-authored source data rather than verified facts or instructions. That untrusted-content warning is exactly the kind of trait structured fields cannot express and directly affects how the agent should treat the payload.

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 tight sentences: the first front-loads what is read, the second carries the trust caveat and prerequisites. Every clause earns its place and nothing is repeated from the title or annotations.

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?

A zero-parameter read with an output schema, so return-format detail is unnecessary, and the description still names the main returned fields plus the revision. Auth prerequisites and the data-trust framing round out everything an agent needs before invoking it.

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 tool takes zero parameters (schema coverage 100%), so per the rubric the baseline is 4. The description adds nothing about parameters because there is nothing to add; the enumerated return fields are useful orientation but not 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?

States a specific verb (Reads) and resource (the connected organisation's profile) and enumerates exactly what is returned: profile, shared assistant notes, update permission, current revision. An agent can tell what this tool fetches. It does not, however, differentiate itself from the sibling get_company_context_template or from update_company_context, which is the only reason 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?

"Requires read consent and organisation membership" gives an explicit precondition for calling, which is real usage guidance. There is no statement of when to prefer this over get_company_context_template or when to reach for update_company_context instead, so no exclusions are offered.

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 it readOnly, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context: it clarifies that this returns guidance/schema rather than company data, preempting confusion with the similarly named get_company_context.

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 short sentences, each earning its place: what it returns, what it enables, and what it does not touch. Front-loaded and free of 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?

An output schema exists, so return values need no elaboration, and the description correctly points at what the response contains (guidance + update schema). Nothing critical is missing for a zero-parameter read tool, though a pointer to the paired update_company_context call would have made it complete.

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?

With zero parameters and 100% schema coverage, the baseline is 4. The description's mention of 'the update schema' adds a small amount of meaning about the payload by signaling that the response includes a schema for the companion update tool.

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?

States a specific verb and resource: returns shared company-context interview guidance plus the update schema. The closing clause ('Does not read or change company records') implicitly separates it from siblings like get_company_context and update_company_context, though those siblings are not named.

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?

'Supports conversation or synthesis from supplied material' hints at the intended workflow but never states when to call this versus get_company_context or get_strategy_template. Usage is implied rather than directed.

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 value beyond them by disclosing the return format (markdown) and the content sections returned, but says nothing about pagination, auth, or error behavior.

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 front-loaded sentence with zero filler: the verb and return format come first, followed by the payload contents. Nothing needs trimming.

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 tool with a defined output schema and full annotation coverage, the description is nearly complete. The one gap is not naming the sibling template tool an agent might confuse it with, which slightly lowers the score.

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 a single parameter documented at 100% schema coverage with pattern and length constraints, so the schema does the work. The description adds no meaning about invention_id beyond what the schema already provides; 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 names a specific verb (Returns) and resource (an innovation record) and enumerates the rendered contents (problem, solution, technical details, prior art). It is clearly distinct from list_innovations, though it never explicitly contrasts itself with siblings like get_innovation_template.

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?

No guidance on when this tool should be selected versus get_innovation_template, list_innovations, or search. The only implicit cue is that it requires an id, but no prerequisites 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral value by disclosing the template's contents and the capture/interview-vs-authoring guidance, going beyond what annotations provide.

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 that leads with what is returned and then qualifies the guidance content. It is dense with an em-dash clause but every phrase carries information; slightly long but not wasteful.

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 zero parameters, a read-only annotation set, and an output schema present, the description need not explain return values. It covers purpose and content adequately; the only minor gap is the absence of explicit sequencing to register_innovation.

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 tool takes zero parameters, so the baseline is 4. The description correctly implies a parameterless fetch of the current template and does not need to describe any inputs.

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?

States a specific verb and resource ('Returns the current innovation registration template') and enumerates the payload (schema, per-field guidance, structure, capture guidance). It is clearly distinguishable from siblings like get_innovation, register_innovation, and list_innovations.

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 context by saying the template is 'used to create a new innovation' and by describing capture guidance 'before drafting,' which hints at use prior to register_innovation. However, it never explicitly states when to call this versus siblings or that it should precede registration, so usage remains inferred.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: a rendering failure degrades to a notice with artifact.status/artifact.reason, and the document body intentionally shows the baseline at amended blocks. Much of the remaining text describes return shape that the output schema already carries, keeping this at a 4 rather than 5.

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?

Front-loads the core purpose in the first clause, but then runs as one long dense paragraph that restates return fields (artifact.markdown, artifact.amendments, trailing text block) likely already covered by the output schema. Several clauses could be cut without losing agent-relevant 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?

Given an output schema exists, the description needn't explain return values, yet it does so thoroughly and additionally covers the degraded-render case, so an agent knows what to expect on failure. The remaining gap is usage context — no guidance on sourcing review_id or handling invalid IDs — which keeps it short of a 5.

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?

Only one parameter (review_id) with 100% schema description coverage, so the schema fully documents it. The description adds no format, sourcing, or lookup guidance for the identifier, which is the baseline 3 case where structured fields do the heavy lifting.

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?

States a specific verb and resource ('Returns a review') and then enumerates the exact payload: metadata, markdown document, comment threads with stable IDs, discussion feed, attorney redlines, and embedded amendments. This clearly separates it from sibling list_reviews (enumeration) and respond_to_review (mutation).

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 explains what comes back but never says when to call it, when not to, or what alternative to use. There is no mention of how to obtain a review_id (e.g., via list_reviews) or how it relates to respond_to_review, leaving the agent to infer all routing.

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 establish readOnly, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds genuine value by disclosing what the payload contains (section identifiers, Markdown body, current revision), which goes 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?

A single front-loaded sentence that names the action, the resource, and the returned content with no filler. Every clause 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?

An output schema exists, so return-value documentation is not strictly required, yet the description still summarizes the payload. For a simple one-param read tool the definition is essentially complete, with only workflow alternatives left unstated.

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?

Only one parameter (strategy_id) with 100% schema description coverage, so the schema fully documents it. The description adds no format, pattern, or lookup detail beyond what the schema already provides, making the baseline 3 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?

States a specific verb (reads) and resource (strategy) and enumerates what is returned: section identifiers, Markdown, and current revision. It implicitly separates itself from edit_strategy/create_strategy by being the read side, though it never names a sibling explicitly.

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?

"for subsequent edits" signals the intended workflow (fetch before modifying), which is useful context. However, it gives no explicit when-not or named alternative, leaving the agent to infer the read-before-edit pattern.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the access prerequisite ('Requires strategy management rights') and the list of what the guide contains, which tells the agent this is a static reference document rather than live strategy data.

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 short sentences, front-loaded with what is returned, followed by usage context and the permission prerequisite. No filler or restatement of the title.

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 0-parameter schema and an output schema present, the description need not explain return structure, and it usefully summarizes the guide's contents and the auth requirement. The only gap is the absence of explicit routing guidance relative to get_strategy and get_innovation_template.

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 tool takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. The description correctly does not waste space on inputs and instead describes the returned content.

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?

Clear specific verb and resource: returns a 'shared conversational capture guide' including readiness criteria, creation schema, and an example. An agent knows exactly what artifact it retrieves. It does not, however, differentiate itself from the sibling get_innovation_template, which appears to play the same role for a different resource.

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?

'Supports interactive capture and drafting from existing material' implies the usage context (preparation before create_strategy), but the description never states explicitly when to call this versus get_strategy or get_innovation_template, nor when it is unnecessary. Usage is inferable rather than directed.

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 declare readOnlyHint=false with no explanatory power, and the description justifies that by disclosing the side effect: it refreshes active analyses and persists their status and findings in Lightbringer. It also explains terminal vs in-progress states and that findings_error does not affect terminal execution status, which is meaningful behavior 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 purpose and return shape are front-loaded in the first sentence, followed by side effects, status semantics, and exclusions, so the structure follows importance. It is slightly dense at four sentences, but each one carries distinct information with no 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 an output schema present, the description needn't re-document return values, and it correctly focuses on the semantics an agent cannot infer: which statuses are terminal, how to read findings_error, and what the endpoint does not cover. The only gap is that it does not describe polling cadence or whether repeated calls advance an analysis, which an agent calling a refresh-on-read tool would benefit from knowing.

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 there is a single task_id parameter, so the schema already documents origin, pattern, and length. The description only restates that task_id comes from start_innovation_feedback, adding no format or edge-case 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 names a specific verb and resource (returns an automated feedback task by task_id) and enumerates exactly what comes back: status, progress, findings, and per-analysis errors. It distinguishes itself from start_innovation_feedback by stating it returns the same shape, so an agent knows this is the polling counterpart rather than a duplicate.

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 gives real routing context: it is the read-side companion to start_innovation_feedback, and it explicitly excludes professional service requests, patent preparation, and filing milestones, which steers the agent away from misusing it for those workflows. It stops short of naming an alternative tool for those excluded cases, so it is strong but not complete when/when-not guidance.

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?

Adds substantial behavior beyond the annotations: own-patent imports auto-attempt family grouping (no separate refresh needed), repeated requests return the existing record without updating it (consistent with idempotentHint), conflicts are raised when purpose or publication differs, and imports cannot change an existing record's purpose or replace its publication. It also explains timeout semantics ('a timed-out request may have saved the record'). This is exactly the context an agent needs before invoking a mutating, open-world tool.

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?

Well front-loaded with the core action, then behavior, then edge cases. It is on the long side for a three-parameter tool, and the receipt.status/receipt.warnings explanation partly duplicates the existing output schema, but every sentence still carries decision-relevant 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 an idempotent, open-world import with an output schema, the description covers conflicts, idempotency, timeout recovery, and immutability thoroughly. The remaining gap is the undocumented competitorCompanyName parameter (when it is required and what it does), which neither schema nor description resolves.

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 33% (only 'purpose' is documented), and the description does elaborate on own vs competitor meaningfully. However, 'competitorCompanyName' is never mentioned in the description despite being undocumented in the schema, and no format guidance is given for 'publicationNumber'. It adds value for one parameter but does not compensate for the coverage gap on the other two.

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?

States a specific verb and resource ('Imports one public patent publication into the connected organisation') and immediately disambiguates the two modes (own vs competitor). An agent can tell this apart from search_public_patents and request_patent_preparation without opening either 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?

Gives clear context for choosing a purpose ('own identifies the customer's own patent... competitor identifies someone else's') and clarifies that ownership should come from user intent rather than search results. It also explains retry behavior after timeouts. It never names an explicit alternative tool or states when not to use this one, 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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds the returned field set, but it omits pagination, result limits, or ordering behavior that would be genuinely useful context.

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 tight sentences: purpose and scope first, then the optional parameter. No filler, no repetition, everything 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?

An output schema exists, so return values need not be re-explained, and this tool has only one optional parameter, making the description sufficient to call it correctly. Minor gaps around result ordering/limits keep it from a 5.

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 single query parameter is documented in the schema as a title/reference filter. The description restates the same optional free-text filter without adding syntax or matching semantics, 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?

States a specific verb and resource (lists innovations) plus the scope (the user's Lightbringer organisation) and the returned fields. It is clearly distinguishable from get_innovation, but it never names a sibling alternative outright, 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?

The organisational scope ('the user's Lightbringer organisation') implies when this tool applies, and the optional filter is described. However, there is no guidance on when to use this versus get_innovation or the generic search tool, and no exclusions or prerequisites.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: results are permission-scoped to reviews the user participates in or created, and strategy reviews are surfaced separately from report reviews — a meaningful behavioral distinction not visible in the schema.

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 that opens with the verb and scope before enumerating fields. It is long, and the field enumeration partially duplicates the output schema, but nothing is padding or tautological.

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 zero-required-parameter list tool with an output schema, the description covers scope, the participant/creator permission boundary, and the strategy-vs-report split. The listed return fields are somewhat redundant given the output schema, but no agent-critical information 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 (status, enum open/closed) and schema coverage is 100%, so the schema fully documents it. The description never mentions filtering by status at all, adding nothing on top of the structured field — baseline 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?

States a specific verb and resource ('Lists reviews') and adds a meaningful scope constraint — only reviews where the user is a participant or creator. That scoping distinguishes it in spirit from the singular get_review sibling, but the description never names that sibling or otherwise explicitly separates the two.

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 by the tool name and the participant/creator scoping, but there is no explicit when-to-use or when-not-to-use statement, and no pointer to get_review for single-record retrieval. An agent must infer the boundary from the sibling list.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds useful scope context (results are limited to accessible strategies in the connected organisation, and publication status is included), but says nothing about ordering, pagination, or result volume.

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 well-formed sentence that front-loads the action and resource before adding the scoping and content qualifiers. 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 zero-parameter read tool with an output schema, the description plus annotations cover what an agent needs: what is returned, whose data, and that the operation is safe. Only minor gaps remain (pagination/ordering), which the output schema may cover.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description's note about access scope is relevant context but is not parameter-related.

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?

States a specific verb and resource (lists strategies) and adds meaningful scope: the ones 'you can access in the connected organisation', plus 'including publication status'. It is distinguishable from siblings like get_strategy, create_strategy and delete_strategy, though it never names them explicitly.

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 by the verb 'lists' – an agent can infer this is the enumeration tool versus get_strategy for a single record. However, there is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives such as search or get_strategy.

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 cover read-only, non-destructive, non-open-world behavior. The description adds substantial behavioral detail: tasks and findings expire 30 days after creation, pagination can return an empty page with a continuation cursor, and status summaries are recorded rather than fetched from upstream analyses.

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?

Front-loads the core list operation, then layers usage, expiration, pagination, and exclusion notes. The six sentences are information-dense, though the final sentence about professional service requests is somewhat tangential.

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?

An output schema exists, so return format need not be explained, and annotations cover the safety profile. The description supplies expiration timing, pagination edge cases, and recovery/status-summary use cases, completing the context an agent needs.

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 67%: cursor and invention_id have descriptions, while limit has none. The description restates the optional innovation filtering and adds pagination behavior, but provides no semantics for limit, so it only partially compensates for the schema gap.

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?

States a specific verb and resource: lists the current user's unexpired automated tasks in the connected organisation, optionally for an innovation. Scope is clear, but no sibling tool is named to explicitly differentiate from get_task_status, list_innovations, or delete_task; the note that professional service requests are separate is too vague to count as sibling routing.

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?

Gives clear usage context: recovers task IDs after a lost response or conversation, and returns recorded status summaries without polling upstream analyses. It also excludes professional service requests, but does not name an alternative tool or provide an explicit when-not condition beyond that.

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?

Goes well beyond the annotations by disclosing that existing relationships are retained and incorrect ones cannot be removed, what stays unchanged (text, PDFs, images, legal status, classification), the return shape (counts, warnings, no member list), and the meaning of a null links result. This is unusually rich behavioral context for a mutation tool.

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 purpose is front-loaded in the first sentence and every sentence carries substantive information, but the description is long and slightly repetitive (multiple sentences about which fields are unchanged and about incomplete updates). It is informative rather than padded, though it could be tightened.

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 a mutation tool with an output schema, annotations, and a single parameter, the description covers behavior, limitations, prerequisites, and result semantics thoroughly. Nothing an agent needs to invoke or interpret it correctly appears to be 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?

Only one parameter and schema coverage is 100%, so the schema already documents documentId and its accepted forms. The description adds no syntax or format detail beyond that, so the baseline 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?

States a specific verb (updates), resource (family grouping), and scope (one saved own patent, drawing on public info plus related saved own patents). It is clearly distinguishable from siblings like import_patent and search_public_patents.

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?

Explicitly names the triggering situations (apparent missing relationship, unfinished family update, checking newer public information) and the when-not ('routine refresh after import is unnecessary', 'repeating import_patent only retrieves its saved outcome'). It also flags prerequisites (related publications must be imported first) and exclusions (competitor records unsupported).

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=false and destructiveHint=false, so the write/non-destructive profile is covered. The description adds real value beyond that: validation runs before any record is created, invalid input yields field-specific errors with no partial record, and non-blocking warnings may accompany success. It does not mention permissions or rate limits, keeping it short of a 5.

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?

Five front-loaded sentences, each carrying distinct content (purpose, validation contract, alternative, patent scope, requirement). Dense and mostly waste-free, though the closing 'Requires a payload matching the current registration schema' slightly restates the opening clause.

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 complex nested-payload creation tool with an existing output schema, the description covers creation semantics, the atomic validation contract, the alternative tool, and scope exclusions. Nothing an agent needs to call it correctly 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?

The single payload parameter is fully documented in the schema (100% coverage), so the schema carries the field-level meaning. The description only adds that the payload must match the 'current registration template,' which is a mild versioning hint rather than substantive parameter guidance, matching the high-coverage baseline 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?

Opens with a specific verb (registers) and resource (innovation) scoped to the user's organisation and a structured payload. It explicitly distinguishes itself from update_innovation, so an agent can select it without opening sibling schemas.

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?

Gives an explicit when ('capturing a concept that is not already recorded') and when-not ('enrichment of an existing innovation belongs in update_innovation'), and it also carves out patent work ('without requesting patent preparation or filing'), routing the agent away from request_patent_preparation.

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=false, destructiveHint=true and openWorldHint=true, so the write profile is covered structurally. The description adds genuinely new behavioral context the annotations do not convey: that targeted users with document access receive email and in-app mention notifications, and that the call returns the created reply.

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, no filler, and the core action plus identifier are front-loaded before the notification side effect. Every clause carries information an agent would not get from the structured fields alone.

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?

An output schema exists, so return-shape detail is not required, and the annotations carry the safety profile for this mutation. Notification behavior is disclosed, but prerequisites such as required permissions or the consequence of the destructiveHint=true flag are not addressed.

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 comment, review_id, comment_id and target_user_ids are already documented. The description adds only marginal meaning for target_user_ids (notification recipients with document access) on top of the schema's own note that identifiers without target access are ignored; baseline 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?

States a specific verb and resource ('Adds a reply to an existing comment thread') plus the identifying key ('comment ID') and the return value. It implicitly distinguishes itself from sibling add_comment/add_discussion_comment by being a reply into an existing thread, but never names those siblings explicitly.

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 only implied: the phrase 'existing comment thread identified by its comment ID' tells the agent this is for threaded replies rather than starting a new comment or discussion. There is no explicit when-to-use/when-not or any mention of the alternative sibling tools that also add comments.

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 write/idempotent/open-world profile, and the description adds real side-effect detail: emails to the assigned specialist and submitter, primary contact copied when applicable, and the caveat that delivery status is not returned. It does not address the destructiveHint=true flag, leaving an agent to wonder what is actually destructive about a workflow advancement.

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?

Four sentences, front-loaded with the action, then side effects, return semantics and exclusions; each sentence carries distinct information. Slightly dense, but there is 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?

Covers the action, preconditions, side effects and even the return semantics of an otherwise idempotent workflow trigger, despite an output schema already existing. Nothing an agent needs to invoke it correctly 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?

Schema description coverage is 100% for the single invention_id parameter, so the schema already documents it fully. The description adds no format, lookup, or validation guidance beyond the schema, so the baseline 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?

Specific verb+resource ("Requests Lightbringer patent preparation") with explicit scope ("for an already registered innovation") and a clear boundary against the neighbouring registration concept. An agent can tell this apart from register_innovation without opening either 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?

Gives a clear precondition (innovation must already be registered) and an explicit exclusion set ("does not itself complete preparation, file a patent or pay for services"). It stops short of naming the sibling tool (register_innovation) or stating when-not to use it in preference to another sibling, so it is strong but not fully routing.

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 flag this as a destructive, open-world write, but the description goes further by disclosing an outbound email side effect and, critically, the state-machine constraints: approval is irrevocable while request_changes can be upgraded later. That irreversibility detail is exactly the kind of behavior an agent must know before committing.

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 compact sentences: what it does, when to call it, and the irreversibility rules. The most decision-relevant constraint (the approval cannot be withdrawn) is front-loaded in the second half rather than buried. No 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 an output schema present, return values need not be explained, and the description covers the mutation's side effects and irreversibility well. It omits any permission/authorization prerequisite for a destructive write on a shared resource, which is the one notable 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 is 100% and the enum for 'response' is documented in the schema, so the schema does the heavy lifting. The description corroborates the two response values narratively but adds no format, length, or content guidance for 'message' or 'review_id' beyond the schema. 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?

States a specific verb (records a decision) and resource (a review), enumerates the two possible responses, and discloses the side effects (email notifications) and return value (updated review state). An agent can distinguish this from get_review or list_reviews without opening a 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?

Explicitly scopes timing: 'Meant for after the user has explicitly chosen their response,' which rules out speculative or exploratory calls. It does not, however, name the read sibling (get_review) as the alternative, so the routing 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 cover the read-only, non-destructive profile, and the description adds substantial behavioural context beyond them: asynchronous indexing delay, empty-result interpretation, cursor-based pagination, query omission behaviour, and that refresh assessment compares stored references without calling a provider or changing records. This is unusually rich disclosure for a read-only search tool.

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 purpose and category scope are front-loaded, but the description is a dense single paragraph with many sentences devoted to return-value details such as IDs, titles, summaries, parts, family overviews, and refresh assessment. Since an output schema exists, some of that space is less necessary, though the edge-case notes about async indexing and empty results are valuable.

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 search tool with four optional parameters, an output schema, and safety annotations, the description covers the important operational context: categories, query omission, pagination, follow-up fetch resolution, async indexing delay, and refresh-assessment behaviour. The main gap is that the limit parameter and some category distinctions are left to the schema.

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 50%, and the description adds meaning for query omission, category filtering (especially meeting transcript/canvas text), and cursor pagination. It does not explain the limit parameter or fully differentiate the enum values application, patent, innovation, competitor_application, report, and meeting, so it only partially compensates for the schema gap.

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 and resource: searches the Lightbringer organisation's documents and meetings, with document categories enumerated. It does not explicitly name sibling alternatives such as search_public_patents or list_innovations, but the organisational scope is clear enough to distinguish it from a public patent search.

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 mostly implied. It notes that omitting query lists accessible records in the selected category and that cursor pagination is supported, and it tells the agent that meeting result IDs resolve through fetch. However, it does not explicitly say when to choose this tool over alternatives like list_innovations, get_innovation, or search_public_patents.

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?

With annotations only saying readOnlyHint=false, openWorldHint=true, destructiveHint=true, the description carries substantial extra context: mcp:write permission required, destination is a human-reviewed Lightbringer Slack channel, only text/category/tool_name are transmitted, no account or client metadata is attached, the channel is hidden from the user, and transcripts/documents/invention details are excluded. This is well beyond what the annotations convey.

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?

Front-loads the purpose in the first sentence and each subsequent sentence covers a distinct consent, permission, or privacy fact. It is on the long side, and the closing sentence partly repeats the earlier 'no metadata / no confidential material' point, but nothing is filler given the privacy stakes.

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?

An output schema exists so return values need no explanation, and the description covers consent flow, required permission, recipient, data-minimization scope, and the visibility caveat. An agent has everything needed to decide whether and how to call it.

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 all three parameters (category, feedback, tool_name) are documented in the schema itself, so the baseline is 3. The description restates the payload contents ('report text, category and optional tool name') but adds no format or constraint detail beyond the schema.

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?

States a specific verb+resource ('Sends feedback ... about the Lightbringer tools') and enumerates the three content types it covers: broken/surprising behaviour, missing capabilities, friction. It is distinguishable from siblings such as start_innovation_feedback because it is explicitly scoped to tool-level issues rather than innovation 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?

Gives a clear precondition (user's explicit consent after seeing the report text, category, optional tool name, and being told the recipient) and a clear content trigger (tool bugs, missing capabilities, friction). It does not name an alternative tool or state when NOT to use it, so it falls 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 destructive=true, idempotent=true, readOnly=false, but the description adds real substance beyond them: the effect on organisation-wide context and existing competitor monitoring, the explicit non-effect on scheduling, concurrency ('multiple strategies may be published simultaneously'), and the rights requirement.

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?

Four short sentences, each carrying distinct information (action, trigger, downstream effect, constraint), with the core action front-loaded and no 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 an output schema present, return values need no explanation, so the description's coverage of authorization, downstream impact, and the non-effect on monitoring makes it complete enough for an agent to call 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 coverage is 50% (strategy_id is documented, the boolean publish is not), and the description compensates by spelling out both boolean states as publish versus return-to-draft. It adds meaning beyond the bare schema, though it never states the parameter name explicitly.

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?

States a precise verb+resource pair ('Publishes a strategy') and covers the reverse transition ('returns it to draft'), making it identifiable against siblings like edit_strategy or delete_strategy without opening either schema. The bidirectional scope is explicit.

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?

Signals the trigger condition ('on explicit user request') and pre-empts a likely misconception with 'Publication does not schedule or start monitoring.' It does not explicitly name a competing sibling to use instead, so it stops short of 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 declare a non-readonly, non-destructive, closed-world write, and the description adds substantive behavior beyond them: the returned task_id/status/progress envelope, the terminal-state semantics (succeeded/partially_succeeded/failed), the fact that ending the wait is not a cancellation, and the findings_error convention meaning unavailable rather than absent. It does not mention auth or rate constraints, but coverage is strong for a task-starting tool.

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?

Front-loaded with the action and focus areas, then the return/state semantics, then the sibling exclusions. Information-dense and free of filler, though the middle stretch packs several distinct facts (statuses, findings_error, wait semantics) into successive short sentences without grouping.

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 a two-parameter, non-destructive write with an output schema, the description covers what is needed: what triggers what, how to continue polling, which states are terminal, cancellation semantics, and error conventions. An agent can invoke and follow up correctly without consulting anything else.

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%, so baseline is 3, and the description earns above it by spelling out the focus values (clarity, problem framing, completeness, all) in prose where the schema's own text is only 'The analysis focus area'. It does not add anything for invention_id, which the schema already documents with pattern and length bounds.

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?

States a specific verb (Starts automated analysis) plus the resource (a registered innovation description) and enumerates the focus areas. It also names the sibling capabilities it is NOT (novelty assessment, patent search, FTO, attorney review, patent preparation), so an agent can discriminate it from surrounding 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?

Explicitly routes ongoing work to get_task_status with the same task_id, states which statuses are terminal, and clarifies that ending the wait does not cancel analysis. It lacks an explicit 'use this when X, use that when Y' trigger statement, but the boundary with adjacent request types is clearly drawn.

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 destructive/non-idempotent annotations, it discloses authorization needs (moderator rights, write consent), optimistic concurrency (stale revisions rejected without changes), merge semantics (omitted fields unchanged, empty strings clear), full-replacement behavior for notes, and the specific side effect of applicant_name on workspace naming.

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?

Dense but waste-free; each sentence carries a distinct behavioral fact (permissions, concurrency, merge semantics, edge-case fields, return value, exclusion). The most important constraints are front-loaded.

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 destructive nested-update tool with an output schema, the description covers permissions, concurrency, field-level merge/clear behavior, the returned value (saved context and new revision), and a boundary exclusion. An agent has everything needed to call 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?

Top-level schema coverage is low, so the description carries weight: it explains the revision requirement and the merge/clear semantics that apply to updates. It details notes and applicant_name precisely, though state and country receive no added meaning beyond the schema's maxLength constraints.

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?

States a specific verb and resource with scope: updates selected profile fields or shared assistant notes in the connected organisation. It explicitly excludes create/publish Strategy, routing the agent away from the create_strategy sibling, and its relationship to get_company_context (source of the revision) is clear.

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?

Says it requires moderator rights and write consent, that the revision from get_company_context is required, and adds a clear when-not ('Does not create or publish a Strategy'). It stops short of naming the read alternative explicitly for the read step, but the prerequisites and exclusion give strong selection guidance.

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 destructiveHint=true and idempotentHint=true, and the description's 'Overwrites the specified sections' is consistent with that. It adds little beyond the annotations, repeating the overwrite semantics already captured by destructiveHint, and says nothing about untouched sections, auth, or 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?

Two short, front-loaded sentences with zero filler; the operation and its overwrite nature are conveyed immediately.

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 full schema, an output schema, and rich annotations, the short description is nearly sufficient. It could still note that unspecified sections are left unchanged and any permission requirements, which are the remaining gaps for a destructive mutation.

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 nested section schema already documents each field's full-replacement and empty-string-clearing behavior. The description only restates 'new content' and 'sections', adding no meaning beyond the schema, so the baseline 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?

States a specific verb (updates) and resource (innovation record sections), plus the scope ('one or more sections') and the return behavior. It is implicitly distinguishable from get_innovation and register_innovation, though no sibling is named explicitly.

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 innovation record' implies this is for modification rather than creation, but there is no explicit when-to-use guidance, no prerequisites (e.g., ownership/permission needs), and no routing to alternatives such as register_innovation or get_innovation.

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, non-destructive and non-open-world, so the safety profile is covered. The description adds genuinely new behavior: the roster is bounded to 20, requires read consent, and a failed member lookup is reported separately rather than failing the whole call.

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 tight sentences, front-loaded with the core result and then the optional member behavior and failure semantics. Minor redundancy with the schema's 'read consent' phrase, but nothing wasteful.

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?

An output schema exists, so return values need not be described. The description still covers the default (profile only), the optional branch, and the partial-failure case, leaving only the default value of include_members to inference.

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%, so the boolean's meaning is already documented (baseline 3). The description adds the concrete bound of 'up to 20' members and the consent condition, which the schema's generic 'bounded member roster' wording does not quantify.

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?

States a specific verb and resource: returns the signed-in user and organisation scoped to this connection. None of the siblings (list_tasks, get_strategy, search, etc.) do this, so an agent can distinguish it at a glance.

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 rather than stated: it is the identity/profile lookup for the current connection, and members are only available 'with read consent'. There is no explicit when-to-use, when-not-to-use, or named alternative, though the siblings suggest none exists for this purpose.

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