Lightbringer

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

Beyond the annotations, it discloses real side effects: targeted users with document access get email and in-app mention notifications, and ambiguous quotes return candidate passages instead of failing blindly. That is meaningful behavioral context for a write tool. The destructiveHint=true annotation is never explained (what, if anything, can be overwritten), which is the main remaining gap.

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, each carrying distinct information: purpose, failure mode, threading rule, notification side effect. It is front-loaded with the core action and free of filler. Slightly dense phrasing in the ambiguity sentence costs it the top mark.

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 and full parameter coverage, the description only needs to cover intent and side effects, which it does, including the partial-success ambiguity case. It stops short of stating prerequisites (access to the review) or characterizing the destructive hint, small omissions for a mutation tool.

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 adds genuine meaning on top: quoted_text must match review markdown and may be ambiguous, and target_user_ids triggers mention notifications while identifiers lacking document access are ignored. Only review_id receives no added semantics, which is fine given its simple pattern.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ("Adds a comment to the document under review") and states the anchoring mechanism (a quoted passage of the review markdown). It never names the closely related siblings add_discussion_comment or reply_to_comment, so an agent must infer the boundary, which keeps it out of 5 territory.

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 context is implied rather than stated: "A comment anchored within an existing thread is added as a reply" hints at routing relative to reply_to_comment, and the ambiguity clause tells the agent what happens on failure. There is no explicit when-to-use/when-not-to-use statement, no mention of required permissions on the review, and no direct comparison with the sibling comment tools.

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 annotations, the description adds real behavioral context: the comment is visible to the review creator and all participants, eligible participants get in-app and email notifications, and the call returns the updated discussion. It does not address reversibility or why destructiveHint is true for what is essentially an additive post, which is the one remaining gap given annotations already flag the mutation profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each carrying distinct information: what it does, how it differs from the sibling, and its side effects. The scope statement and the sibling contrast are front-loaded 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?

For a two-parameter mutation with full schema coverage, an output schema, and annotations, this covers purpose, differentiation, and notification side effects well. Only the destructive-flag semantics and any permission requirements (who counts as an eligible participant who may post) are left implicit.

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 both parameters (comment, review_id) are already documented with types and constraints. The description adds only mild framing — that the comment lands in the review's discussion feed — without clarifying identifier format or length expectations beyond the schema, so 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?

The description opens with a specific verb and target ("Posts a standalone comment to the review's discussion feed") and explicitly contrasts the scope with the sibling add_comment (not anchored to a passage). An agent can distinguish it from add_comment and reply_to_comment without consulting 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?

It states the alternative explicitly (add_comment, which is passage-anchored) and names the situations this tool is for: general remarks, questions, or status updates about the review as a whole. The routing decision is fully determined by the text.

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 annotations it discloses that the result is saved as a draft, that write consent and Strategy management rights are required, and that a repeat call can produce a duplicate. That duplicates point is the key behavioral risk and it is stated explicitly, matching the non-idempotent annotation rather than contradicting it.

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 and scope in the first two sentences, then auth, return value, and duplicate risk in descending priority. It runs five sentences and the fetch/include_asset aside is slightly fussy, but no sentence is pure filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter write tool it covers the essentials: what is created, in what state, under what permissions, what comes back, and how to recover from an ambiguous retry. The return-value sentence is partly redundant given the output schema exists, and the sibling overlap remains unresolved.

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%, and the nested object carries its own required fields and constraints, which the description largely restates ("a title and populated Markdown sections"). The one genuine addition is naming the section body as Markdown, a semantic the schema's opaque string pattern cannot convey.

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?

"Creates one asset" gives a specific verb and resource, and the second sentence narrows scope to a Strategy with title plus populated Markdown sections saved as a draft. However, it never distinguishes this tool from the sibling create_strategy, which appears to do an overlapping job, so the boundary is left obscure.

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 routes the agent away from publication and patent work ("separate actions") and explains that uncertain outcomes should be reconciled via search rather than retried. That is real when/when-not guidance, but the most pressing alternative question — create_asset vs create_strategy — goes unanswered.

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 supplied annotations, it discloses validation before saving, required strategy-management rights, draft rather than published state, and the saved link and revision returned on success. The shared-record behavior with create_asset adds further useful interoperability 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?

The description is dense but efficiently ordered, leading with deprecation and its replacement before covering purpose, workflow, behavior, and permissions. Each sentence supplies distinct, actionable information without 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?

For a two-parameter create operation with an output schema and safety annotations, it covers tool selection, lifecycle, validation, authorization, and publication boundaries well. Its main completeness gap is relying on a separate template tool for parameter and capture semantics.

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?

Neither title nor sections is directly explained despite 0% schema description coverage. The pointer to get_strategy_template for capture guidance and schema partially compensates, but the description itself adds little about expected section content or how the parameters should be populated.

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 explicitly states that it "Creates a populated draft strategy" and distinguishes this deprecated interface from create_asset, while noting that both access the same Strategy records. This provides a specific action, resource, resulting state, and clear sibling differentiation.

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 explicit migration-based selection guidance: the interface is retained for existing clients, while create_asset is the replacement. It also directs agents to get_strategy_template for capture guidance, edit_strategy for refinement, and clarifies that publication is a separate operation.

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, idempotentHint=true, and readOnlyHint=false. The description meaningfully adds that deletion is permanent, requires write consent and Strategy management rights, and excludes other asset types and patent-service request withdrawal, which are useful behavioral constraints beyond the structured hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four short sentences with the core action front-loaded, followed by scope, authorization, and exclusions. Every sentence contributes useful operational context without unnecessary wording.

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, single-parameter tool with rich annotations and an output schema, the description covers permanence, authorization needs, supported asset type, and important exclusions. The main remaining gap is not clarifying the relationship with the delete_strategy sibling tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already defines the nested asset object, constrains type to strategy, and documents the id pattern and report reference. The description adds the user-selection constraint and repeats the strategy-only limitation, but it does not add much parameter-level meaning 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?

The description states a specific verb and scope: permanently deletes one asset, currently limited to Strategies. It is clear what the tool does, but it does not distinguish this generic asset-deletion tool from the sibling delete_strategy, which is an important ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an implied usage condition by saying the asset must be explicitly selected by the user, and it lists exclusions such as not deleting other asset types or withdrawing patent-service requests. However, it does not explain when to choose delete_asset versus delete_strategy, so guidance is incomplete for sibling selection.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds context those annotations cannot carry: permanence, the deprecation/migration status, and a required permission ('strategy management rights'). It stops short of describing downstream effects (e.g., what happens to dependent assets), which keeps it from 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?

Four short sentences with no filler, and the deprecation notice is front-loaded where an agent will see it first. 'Both interfaces access the same Strategy records' is slightly redundant with the replacement pointer but does usefully signal equivalence.

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, annotations cover the safety profile, and the single parameter is fully documented, so the description only needs routing and risk context — which it supplies. Nothing an agent needs to call this 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% with a single documented 'strategy_id' parameter (pattern, length bounds), so the schema already carries the parameter semantics. The description adds nothing about the identifier format or whether IDs are shared with delete_asset. 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 and resource ('Permanently deletes a strategy') and explicitly positions itself against the sibling that replaces it ('the replacement is delete_asset'). An agent can distinguish it from delete_asset and create_strategy 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 explicit routing guidance: prefer delete_asset, use this only for existing clients during migration and only when 'explicitly requested by the user'. The rights prerequisite is also named, so an agent knows both when to call it and when not to.

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 destructiveHint=true and idempotentHint=true, so the safety profile is known; the description still adds real context by naming exactly what is destroyed (the task and its cached findings), the ownership constraint, and that repeat calls surface not_found. That last point usefully nuances what "idempotent" means here, though it sits close enough to the annotation that it could read as a partial tension rather than a contradiction.

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 with no filler: the destruction is front-loaded, the availability note follows, and the non-effects and repeat-call behaviour close it out. Every clause carries information an agent would otherwise have to guess.

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 destructive tool with an output schema, the description covers scope, side effects, exclusions, and repeat behaviour. The only omission is error/permission handling beyond not_found, which is a minor residual gap rather than a blocker to 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 coverage is 100% with a single well-documented task_id, so the schema carries parameter meaning. The description adds only indirect semantics via the ownership and organisation scoping, which implies the identifier must belong to the caller's tenant but does not spell out behaviour for an out-of-scope or malformed id.

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 ("Permanently deletes an automated task") plus ownership and tenant scope ("owned by the current user in the connected organisation") and the payload affected ("cached findings"). This cleanly separates it from read-side siblings such as get_task_status and list_tasks, and from the unrelated delete_asset and delete_strategy.

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 applicability condition ("Available in any execution state") and strong exclusions: it does not cancel a running analysis, delete the innovation, or withdraw a professional service request. The gap is that it never names which sibling to use for those alternative intents, leaving the agent to infer the 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 destructive=true, idempotent=false and openWorld=false, and the description adds substantial context beyond them: edits are atomic, redlines are not produced, unchanged text and comment anchors are preserved, ambiguous matches and edits touching pending application-editor changes are rejected, conflicting revisions abort without applying changes, and the response exposes orphaned_discussion_ids. The only gap is that it never says what a successful response looks like beyond that one field, though an output schema covers it.

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 deprecation and replacement routing are front-loaded, which is the right priority. A few sentences are dense and mix concerns ("Replacements apply directly, without redlines, and preserve unchanged text and comment anchors"), and the sentence about both interfaces accessing the same records is filler, but overall there is little wasted text.

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, non-idempotent mutation with an output schema, the description covers the important behavioral surface: atomicity, failure modes, concurrency safety via revisions, side effects on discussion threads, and authorization. It is only short of complete on per-action semantics of the operations array.

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 33% — only strategy_id is documented in the schema, while revision and operations are not. The description compensates partially by tying revision to get_strategy and stating that conflicting revisions are rejected, and by characterizing operations as an atomic batch. It does not explain which operation types exist (insert/replace/delete/reorder/rename), the meaning of index or section_ids, or the item limits, so the compensation is incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete operation (an atomic batch of section edits on Strategy records) and explicitly distinguishes it from its replacement, update_asset, plus the related read tool get_strategy that supplies the revision. An agent can pick the correct tool 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?

It states that this interface is deprecated and that update_asset is the replacement, with the condition for continued use (existing clients during migration). It also states the access prerequisite (strategy management rights), so when-to-use versus when-to-use-the-alternative is explicit.

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

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

Annotations only cover the safety profile (readOnly, non-destructive, closed-world); the description adds substantial behavior beyond that: vault download links expire in about an hour, text/code content caps at 256 KB, stale cursors require restarting, and 'This reads stored content without importing, repairing, or contacting a patent provider.' It also explains that a bare document ID resolves to the most advanced text and that missing/unknown sections are distinct from page completeness — exactly the side effects an agent needs to know.

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?

It opens with an edge-case option (`include_asset`) instead of the tool's purpose, which only appears mid-paragraph. The rest is a single dense block covering pagination, cursors, blocks, part IDs, warnings, and legacy behavior with no structural separation, so the critical read semantics compete with incidental detail for attention.

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 five-parameter read tool with an output schema, the description covers everything an agent needs to invoke it correctly: id forms, mode, include/cursor interaction, pagination completion, and the no-side-effects guarantee. Some return-value detail duplicates what the output schema probably encodes, but nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description earns more by explaining semantics the schema only gestures at: part ID syntax (`document:<id>#priority_draft`, `document:<id>#application_text:<revisionId>`), that `include_asset` cannot combine with `include`/`mode`/`cursor`, and that omitting all options yields legacy full content. It adds meaning rather than restating types.

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 second sentence states a specific verb and full resource scope: 'Returns the full content of a single document — invention, patent application, strategy, or report — or a meeting or vault file identified by its search result ID.' That is enough to separate it from `search` and `list_*`. It does not, however, distinguish it from close siblings like `get_innovation`, `get_strategy`, or `get_review`, which plausibly also read a single record.

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?

There is real how-to guidance: 'Pass a part ID to read that text instead' and 'For a known document ID, mode: "outline" discovers native section availability without full text.' But this is parameter-level usage, not tool selection — nothing says when to call `fetch` versus `get_innovation`, `get_strategy`, or `search`, and no exclusions between siblings are given.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: the consent and organisation-membership prerequisites, the fact that a revision value is returned, and a trust caveat that notes are user/agent-authored source data rather than verified facts or instructions.

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 with no filler: the first lists what is returned, the second carries the trust and prerequisite caveats. Front-loading is good, though the trust warning could be compressed without losing force.

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 and pagination need not be explained, and the description covers access prerequisites and data trust, which the schema cannot. The one real gap is the absence of any reference to the closely named template sibling, which is the main ambiguity an agent faces here.

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; the baseline for a parameterless tool applies. The description correctly implies no inputs are needed.

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 ('Reads the connected organisation's profile, shared assistant notes, update permission and current revision'), so the agent knows exactly what comes back. However, it does not distinguish itself from the sibling get_company_context_template, which an agent could plausibly confuse with this one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word 'Reads' implicitly contrasts with the sibling update_company_context, and the consent/membership prerequisites hint at when the call is valid. But there is no explicit statement of when to use this versus get_company_context_template or after which mutation it should be re-read, so the agent must infer 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds useful context by stating the returned payload shape (guidance + update schema) and explicitly denying any read or mutation of company records, which prevents an agent from assuming a side effect.

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 the return content and ending on the strongest constraint. The middle sentence about 'conversation or synthesis from supplied material' is the softest and earns its place least, but nothing is padded or repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, an output schema present, and annotations carrying the safety profile, the description supplies what an agent needs: what comes back and what it must not assume. It falls short only on the when-to-use framing relative to get_company_context, which is the one remaining 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?

There are zero parameters and full schema coverage, so no parameter explanation is required. The baseline of 4 applies since the description correctly implies a no-argument call.

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: it returns shared company-context interview guidance plus the update schema. The final sentence ('Does not read or change company records') separates it from get_company_context and update_company_context, which are the nearest siblings, though neither is named directly.

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' gestures at usage but is too abstract to route reliably. The exclusion of record reads implies 'use this to learn the interview structure, not to fetch data,' but the description never states the condition that selects this tool over get_company_context.

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

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

The annotations already establish a safe read-only, idempotent, closed-world operation. The description adds substantial behavioral context beyond that: it defines disabled/internal/exempt as no-charge states with null fields, explains that exhausted means the balance is spent, and clarifies that paid automated analysis is charged by model usage rather than a fixed price.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the return semantics and contains no filler. The opening sentence is long and dense with multiple clauses, but every sentence contributes useful meaning about statuses or charging behavior.

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 zero parameters, rich annotations, and an output schema, the description is complete enough. It explains the key status semantics and cost model that an agent would need to interpret the response correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so the baseline is 4. The description correctly adds no parameter guidance because there is nothing to clarify.

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 read operation: it returns the connected organisation's credit-charging status, balance, refusal-at-zero behavior, and per-operation costs. This is unambiguous and immediately distinguishes get_credits from every sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the returned cost information for patent import and public patent search, but the description never explicitly says when to call this tool, such as before a paid operation. There are no alternatives to route between, but the when-to-use guidance remains implicit 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description does not contradict it. The description adds that output is markdown-formatted with named sections, which is real context beyond the annotations. It stops short of anything about size, truncation or the shape of the illustrated variant beyond the section name.

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, the output shape first and the optional flag second, with no filler. The conditional is clearly signposted with "With include_illustrations", so the agent can parse the branch at a glance. Slightly dense phrasing in the second sentence is the only friction.

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 does not need to enumerate return fields, and it still names the salient ones. For a two-parameter read-only tool the definition covers the important ground; the missing piece is routing guidance against get_innovation_template and list_innovations.

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 both parameters are already documented, and the baseline of 3 applies. The description reinforces the conditional behavior of include_illustrations and adds a nuance the schema only hints at (drawings it suggests preparing), but it offers no format or constraint detail for invention_id beyond the schema's pattern and length rules.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ("Returns an innovation record") and enumerates its contents: problem, solution, technical details, prior art, and markdown rendering. That is enough to separate it from list_innovations, but it never names the sibling it is not (e.g. get_innovation_template) or says which one to pick for a template versus a record.

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: an agent infers this is the fetch-single-record call from the verb and the required invention_id. The only explicit guidance is attached to include_illustrations ("for example to check what is there before uploading"), which is useful but scoped to one parameter. Nothing states when to prefer this over list_innovations or get_innovation_template.

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 and the description correctly does not repeat it. It adds genuine behavioral context beyond the annotations by disclosing the payload composition (schema, per-field guidance, structure) and the intended capture workflow of interviewing versus authoring from existing material.

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?

It is a single front-loaded sentence that leads with the concrete resource returned and then layers in the capture-guidance detail. The em-dash clause ('interviewing an inventor who is present, or authoring from existing material') is dense but earns its place by describing the workflow the template supports; the sentence is borderline overloaded but not padded.

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, an output schema present, and annotations covering the safety profile, very little burden remains on the description, and it still explains both what comes back and how the guide is meant to be used. The only gap is that it never explicitly frames itself as the prerequisite step to register_innovation, which would make the workflow chain unambiguous.

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 and the baseline of 4 applies. The description correctly spends no words on arguments.

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 the current innovation registration template') and enumerates its contents: schema, per-field guidance, structure, and capture guidance. It implicitly distinguishes itself from get_innovation (an actual record) and register_innovation (the write), but never names those siblings outright.

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 through the phrase 'before drafting' and the mention of interviewing an inventor or authoring from existing material, which hints at a pre-authoring step. There is no explicit statement such as 'call this before register_innovation' or any exclusion telling the agent when another template tool (get_company_context_template, get_strategy_template) is the right choice.

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 read-only, non-destructive, closed-world behavior, so the bar is lower, yet the description adds real behavioral detail: rendering may fail and be replaced by a notice with artifact.status/reason, amendments are surfaced in two places simultaneously, and the document body deliberately shows baseline text at amended blocks. These are non-obvious traits an agent could not get from 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 first clause is well front-loaded, but the remainder is one dense ~190-word paragraph mixing return-value documentation, amendment semantics, failure modes, and a review-type special case. Much of the return-value detail duplicates what the output schema already declares, and the lack of any structural breaks makes it hard to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the return-value exposition is arguably surplus, but it is accurate and covers the tricky cases (unrenderable document, dual amendment representation, ENTRY_PLAN_VALIDATION reviews). What is missing is the small connective detail of how an agent obtains a review_id, which list_reviews presumably supplies.

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, review_id, and the schema already documents it fully (100% coverage) with pattern and length constraints. The description adds nothing about the identifier's format or provenance (e.g., where to obtain one), 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?

Opens with a specific verb and resource ("Returns a review") and immediately enumerates the distinct payload components: metadata, document as markdown, comment threads with stable IDs, discussion feed, redlines, and amendments. This is clearly the single-review read tool, distinguishable from list_reviews and from the mutation siblings like respond_to_review.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the agent can infer this is the fetch-by-id counterpart to list_reviews, but no sentence says so or explains when to prefer it over list_reviews. The one explicit routing hint is that the validation field carries country codes "for set_validation_countries," which usefully links to a sibling, but only for that narrow case.

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 readOnly, non-destructive, closed-world behavior, so the description doesn't need to. It adds genuinely useful context beyond them: deprecation/migration status and what the read returns, including that the revision is intended for subsequent edits. It stops short of noting pagination or any rate/size constraints on the Markdown 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?

Front-loaded with the most decision-relevant fact (deprecation and the `fetch` replacement), which is good structure. However, the three opening sentences restate the same point about compatibility and migration, so a small amount of wording could be trimmed.

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 one-parameter read tool with an output schema and full annotation coverage needs little prose; the description supplies the deprecation caveat and a summary of returned fields. Nothing required 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?

There is a single parameter with 100% schema description coverage and a pattern/limits already documented, so the schema does the parameter work. The description adds no format or semantics beyond 'strategy_id', which is the expected baseline here.

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 ('Reads a strategy') plus the exact payload (section identifiers, Markdown, current revision), and explicitly frames it as a deprecated compatibility interface whose replacement is `fetch`. An agent can distinguish it from fetch, list_strategies, and get_strategy_template 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 explicit when-to-use guidance by naming the preferred alternative (`fetch`) and stating both access the same records, plus the condition under which this tool remains appropriate (existing clients during migration). Effectively tells the agent to prefer another sibling in almost all cases.

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 one genuinely useful behavioral fact beyond that: the call requires strategy management rights, i.e. an auth prerequisite. It says nothing about size or caching of the returned guide, so it earns credit above baseline but not richly.

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, with the returned content front-loaded and the permission requirement last where it belongs. No filler, though 'shared conversational capture guide' is a somewhat opaque phrase that could be phrased more concretely.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no inputs, an output schema, and strong annotations, the remaining burden is small: say what comes back, what it is for, and who may call it — all present. Only the relationship to create_strategy and the other template getters is left implicit.

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 meaning to explain and the schema is empty by design. Baseline 4 applies; the description correctly says nothing spurious about 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?

The description names a specific verb (returns) and enumerates the concrete payload: the shared conversational capture guide, readiness criteria, creation schema, and an example. That distinguishes it from the sibling template readers (get_company_context_template, get_innovation_template) by domain, although it 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?

It gives a use context ('supports interactive capture and drafting from existing material') and a precondition ('Requires strategy management rights'), which implies when to call it. However, it never states when to prefer create_strategy directly, nor does it exclude any scenario, so routing must still be 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?

Despite having only a task_id parameter, the description discloses a real side effect: active analyses are refreshed and their status and findings saved in Lightbringer, which explains the non-read-only hint. It also explains that findings_error marks unavailable findings without altering terminal execution status, a nuance annotations cannot express. It could go further on whether refresh is throttled or whether repeated calls incur cost.

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 what is returned, then covers refresh behavior, status semantics, and exclusions in a tight sequence with no filler. The terminal/non-terminal sentence pairs two clauses efficiently rather than listing values separately.

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 restated, and the description instead supplies the operational context an agent needs: state semantics, side effects, error-field interpretation, and explicit out-of-scope domains. Nothing material for correctly invoking this tool 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 coverage is 100% and the schema already documents task_id as coming from start_innovation_feedback or list_tasks, so the description's mention of task_id adds nothing new. Baseline 3 applies since the schema carries 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 and resource ('Returns an automated task by task_id') and immediately scopes the resource to automated tasks, explicitly excluding professional service requests, patent preparation, and filing milestones. That negative scoping separates it from siblings like list_tasks and get_review without the agent needing to inspect 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?

Explains that this is for retrieving a single automated task by id and clarifies which status values mean work is finished versus still running, which tells the agent when polling is worthwhile. It does not explicitly route the agent to list_tasks for enumeration (that link lives only in the schema), so it stops short of full alternative-routing 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 only give the generic safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=true), and the description adds substantial context beyond that: idempotent behaviour is spelled out as returning the existing record without updating it, conflicts are explained, credit refusal and free-retrieval semantics are stated, and family grouping side effects are disclosed. It even pre-empts a common misread by clarifying that an incomplete receipt does not mean work is still running.

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 core purpose and the own/competitor distinction are front-loaded, which is good, but the remainder is a dense prose block of a dozen sentences mixing idempotency, receipt semantics, credit rules and conflict handling. All of it is useful, yet the lack of any structure (sentences or bullets grouping the receipt/credit/conflict behaviours) makes it slow to scan for the one detail an agent needs.

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 write tool with an output schema, the description covers the return contract well — imported, receipt.status values, receipt.warnings, and null receipt meaning — so it does not need to restate the schema. The remaining hole is competitorCompanyName semantics and whether it is conditionally required, which is the one thing an agent could get wrong at call time.

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%, so the description has to carry meaning. It does well on purpose (own vs competitor, and that it comes from user intent) and reinforces that publicationNumber must be complete, but competitorCompanyName is never mentioned at all — an agent gets no hint about when to supply it or how it interacts with purpose=competitor.

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?

"Imports one public patent publication into the connected organisation" names a specific verb and resource, and the own/competitor split separates it from search_public_patents (discovery) and refresh_patent_family (maintenance). An agent can place this tool among its siblings 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?

Explicit routing guidance: own vs competitor is defined by the customer's intent rather than search results; repeated requests are safe to retry; a timed-out request can be re-run to retrieve the saved outcome; and get_credits is named as the way to check whether a new import costs anything. It also states what the tool cannot do (change purpose, replace publication), which is when-not-to-use guidance in practice.

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 and scope are covered. The description adds that results carry a title, reference number and web link, but since an output schema exists this is largely redundant, and it says nothing about pagination, result caps, or ordering.

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 with the core purpose front-loaded and no filler. The return-field sentence is slightly wasted given the output schema, but the overall structure is tight.

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-optional-parameter read tool with full annotations and an output schema, the description covers scope, filtering, and result content adequately. Missing pagination or result-limit guidance is the only meaningful 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 description coverage is 100% and the single parameter is already described as a 'Free-text filter on title/reference'. The description's 'optional free-text query to filter results' restates the schema without adding matching syntax, case sensitivity, or partial-match behavior, 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 uses a specific verb and resource ('Lists the innovations') and scopes it to the user's Lightbringer organisation, which clearly separates it from single-item siblings like get_innovation. It stops short of naming alternatives such as search or list_strategies, so sibling differentiation is implicit rather than 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?

Usage is implied by the list-nature of the tool and by the optional filter, but the description never states when to prefer this over get_innovation, search, or list_strategies. There are no exclusions or prerequisites, leaving the agent to infer selection criteria from the sibling names alone.

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

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

The annotations already establish read-only, non-destructive, closed-world behavior. The description adds useful behavioral detail about result scope, included fields, and the separation of strategy reviews from report reviews, though it does not mention pagination or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two front-loaded sentences with no filler. The first sentence is dense because it enumerates returned fields, but every clause carries useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with one optional parameter, full schema coverage, annotations, and an output schema, the description covers the scope and contents sufficiently. An agent can invoke it correctly without additional descriptive context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single optional status parameter is fully documented in the schema with an open/closed enum. The description does not mention the status filter or add meaning 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 gives a specific verb and resource ("Lists reviews") and a clear scope: reviews where the user is a participant or creator. It also distinguishes strategy reviews from report reviews, but it does not explicitly differentiate this list operation from the sibling get_review tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives such as get_review, nor any when-not conditions. The participant/creator scope implies what results appear, but not when an agent should choose this tool over a single-review fetch.

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 genuinely new context beyond that: the tool is deprecated, both interfaces hit the same Strategy records, and results include publication status. It doesn't discuss scope limits or pagination, which keeps it short of a 5 for a list operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the most decision-relevant fact (deprecation and replacement) before the functional description, which is the right ordering. Slight redundancy: "Both interfaces access the same Strategy records" largely restates the replacement clause, costing a sentence that could be trimmed.

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 explained in prose, and the tool has no parameters to document. For a simple zero-argument list operation, the description covers purpose, deprecation status, replacement path, record equivalence, and a hint at result content — nothing an agent needs 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The mention of organisation-scoped access and publication status usefully frames what the implicit (unparameterised) result set contains.

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 strategies you can access in the connected organisation") and immediately flags the tool as a deprecated compatibility interface. It also names the exact replacement call ("search with category: \"strategy\""), so an agent can distinguish it from siblings like get_strategy or list_innovations 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 gives both the when-not ("Deprecated... the replacement is search with category: \"strategy\"") and the when-still ("Retained for existing clients during migration"). An agent knows to prefer search for new work and only fall back here for legacy compatibility, with the equivalence of the two 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?

Beyond the read-only, non-destructive, non-open-world annotations, the description discloses ordering (newest to oldest), expiry (feedback tasks and findings expire 30 days after creation), pagination behavior (empty page with continuation cursor), and the semantic distinction that feedback summaries are recorded states rather than live polling. These are substantive behavioral details the annotations do not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose and each sentence adds relevant operational context. It is slightly dense with caveats, but there is no clearly wasted wording.

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 output schema, annotations, and structured input schema, the description is complete enough for an agent to call the tool correctly. It covers purpose, scope, ordering, expiry, pagination quirks, and a boundary against professional service requests.

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 67%, with cursor and invention_id already described in the schema. The description adds some meaning around optional innovation filtering and pagination behavior, but it does not explain the limit parameter at all. Baseline 3 is appropriate for this medium schema coverage.

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 ('Lists'), resource ('automated tasks'), scope ('current user’s ... connected organisation'), ordering ('newest to oldest'), optional innovation filter, and included status. It also distinguishes some boundaries ('Professional service requests are separate'), but does not explicitly name the sibling get_task_status or otherwise fully differentiate from every alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage context: recovers task IDs after a lost response or conversation, and notes pagination can return an empty page with a continuation cursor. It does not explicitly say when to use this versus get_task_status or other task-related siblings, so it lacks full alternative 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 cover read-only and non-destructive nature, yet the description adds real behavioral context: permission-derived result sets, the meaning of an empty result, and pagination behavior (up to 25 per page with a next-page cursor). It stops short of disclosing ordering or whether the cursor expires, so not 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?

Four short sentences, front-loaded with what the tool is and what it returns, followed by scoping and pagination. Slight redundancy: listing the returned row fields partly duplicates the existing output schema, but no sentence is wasted.

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 two-parameter, read-only, paginated list tool with a full schema and an output schema, this covers the essentials: what is returned, what is excluded, who sees what, and how to paginate. Only ordering/tie-break behavior and cursor lifetime are 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?

Schema coverage is 100%, so both limit and cursor are already documented in the schema, and the description only restates the page size and cursor chaining. It adds a little framing (25 per page) but no format or edge-case detail beyond structured fields, 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 and resource ("Lists the trade secret register entries") scoped to the connected Lightbringer organisation, and names exactly what is returned (reference, title, status, dates). Explicitly says "Entry content is not included," which separates it from any content-retrieval sibling like get_innovation or 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?

Explains the result-scoping rule (entries follow the user's register access, empty list = no openable entries), which is genuine usage context. However, it never names an alternative tool or states when to prefer this over list_innovations, list_strategies, or search, so routing guidance is only implied.

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 annotations: it discloses that existing relationships are retained so bad links cannot be removed, that text/PDFs/legal status/classification are left unchanged, that competitor records are unsupported, that a null links result means the update did not finish, and that refreshes cost credits and are refused when credits are exhausted. All of this is consistent with destructiveHint=false and idempotentHint=true.

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 well front-loaded: purpose first, then when-to-use, then constraints, then result semantics. A few sentences are long and could be split, but no sentence is filler and each carries operational 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?

Covers what the tool does, when to use it, what stays unchanged, cost/refusal behavior, and result shape, including the important caveat that no family-member list is returned and results do not establish complete coverage. Despite an output schema existing, the added clarification about results is not redundant noise.

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 single parameter is already documented, so the schema does most of the work. The description still adds meaning by narrowing the valid input to an own patent record and stating competitor records are not supported, preventing a wrong-id call.

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 ('Updates family grouping for one saved own patent') plus the data sources it draws on (public patent information, related own patents already saved). 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?

Gives explicit triggers ('apparent missing relationship, an unfinished family update, or a requested check against newer public information') and exclusions ('Imports already attempt family grouping automatically; routine refresh after import is unnecessary'). It also names alternatives and their limits: 'Repeating import_patent only retrieves its saved outcome' and related publications must be imported separately first.

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 real behavior beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false): validation happens before any write, failures return field-specific errors with no record created, and successful calls surface an identifier, reference number, web link, and non-blocking warnings. It stops short of stating permission requirements, duplicate-detection behavior, or idempotency, so it is strong but not exhaustive.

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 purpose, then behavior, then routing in three tight sentences. Slight redundancy between the opening clause about the 'registration template' and the closing sentence about the 'registration schema', which could be merged.

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 but deeply nested mutation tool with annotations and an output schema, the description covers what it does, the atomic validate-then-create semantics, and the sibling boundary. It could still point at get_innovation_template as the way to obtain a valid payload shape, which is the main remaining 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?

With one parameter and 100% schema coverage, the deep nested schema already documents every field, so the baseline is 3. The description contributes that the payload must match the 'current registration template' and the authoring version contract is implied by the schema, but it never names get_innovation_template as the source of that shape, so it adds only modest meaning.

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 ('Registers a new innovation in the user's Lightbringer organisation') plus the scope of input ('from a structured payload matching the current registration template'). It also names the sibling it is not (update_innovation), so an agent can separate creation from enrichment 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 gives the when: 'capturing a concept that is not already recorded', and the when-not with the named alternative: 'enrichment of an existing innovation belongs in update_innovation'. It also carves out the downstream patent workflow ('without requesting patent preparation or filing'), which routes 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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavior beyond them: a two-phase commit ('until this succeeds the file is not added') and the retry semantics ('registering again after success returns the same result'). It omits one behavioral detail an agent may need — how the destination (Illustrations vs. vault folder) is chosen, since no destination parameter exists.

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 the precondition and destination before the retry notes; nothing is padded. The closing pair of sentences about re-registering is slightly redundant with the idempotent annotation and could be tightened into one 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?

A confirmed-write tool with an output schema, so return values need not be explained, and the description covers the workflow, the failure/retry path, and the post-success no-op. The remaining gap is the destination-selection mechanism, which matters for a tool that can write to two quite different places.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented there, including the 'Illustrations only' scoping of description, so the baseline is 3. The description's only parameter-adjacent content ('the same upload', 'what the drawing shows') restates the schema rather than adding format, constraints, or defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a precise verb and resource ('Finishes an upload') and anchors it to the exact upstream step, the PUT to the URL from request_upload_url. It also names the two possible destinations (Illustrations section of an innovation vs. vault folder), which lets an agent separate this from request_upload_url and create_asset 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?

It states the precondition for calling (file must have been PUT to the URL from request_upload_url) and handles the retry case explicitly: if the file has not arrived or Lightbringer asks to try again, the same upload can be re-registered. It does not explicitly say what not to use it for or name a competing tool, which keeps it just below 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=false, destructiveHint=true and openWorldHint=true, so the safety profile is known. The description adds genuinely useful behavior beyond that: it confirms the created reply is returned and discloses the notification side effect (email and in-app mentions to targeted users with document access), which an agent could not infer from 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 well-formed sentence that front-loads the action and its target, then the side effect. No filler, though combining the mutation and notification semantics in one sentence makes it slightly dense.

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, and annotations cover the mutation profile. However, for a write tool that triggers outbound notifications, the description omits permission prerequisites and any note on whether the reply or notifications can be undone, leaving a moderate 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 description coverage is 100% and each parameter is documented in the schema, so the baseline is 3. The description adds only marginal meaning, clarifying that comment_id addresses an existing thread and that targeting drives notifications, but it does not explain the review_id/comment_id relationship or what role review_id plays in scoping.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ('Adds a reply to an existing comment thread') and identifies the keying mechanism ('identified by its comment ID'), which is enough to distinguish it from a generic comment-creation tool. It does not explicitly name or contrast with siblings like add_comment or add_discussion_comment, so it stops short of full differentiation.

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' suggests this tool is for replies rather than top-level comments, but there is no explicit 'use this when... instead of add_comment' routing, and no stated prerequisites such as needing access to the review. The agent must infer the choice from the name and schema.

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 a destructive, idempotent, open-world write, and the description adds substantive context beyond them: it advances the description into the Lightbringer workflow, sends email notifications to specialist and submitter with the primary contact copied when applicable, and returns whether preparation was newly requested or already existed (consistent with idempotentHint). It also discloses a real limitation — email delivery status is not included — and defines what the call does NOT do, so there is no contradiction with destructiveHint.

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 target, then the side effects, the return value, and the boundaries in a logical order with no filler sentences. The middle sentence is dense but each clause carries distinct information; a slightly tighter phrasing would reach a 5.

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, yet the description still summarises the meaningful return distinction (newly requested vs. already requested) and warns that email delivery status is absent. With prerequisites, side effects, and scope limits all stated, nothing an agent needs in order to call this 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 coverage is 100% for the single invention_id parameter, so the schema already carries the semantics. The description ties the call to 'an already registered innovation', which implicitly tells the agent what the identifier must reference, but adds no format or sourcing detail beyond that. Baseline 3 applies when the schema does 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 ('Requests') and resource ('Lightbringer patent preparation') scoped to 'an already registered innovation', and explicitly separates itself from registration ('Separate from registration'). An agent can distinguish this from register_innovation or import_patent 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 a clear usage condition (innovation already registered, user has decided to pursue filing) plus explicit exclusions ('does not itself complete preparation, file a patent or pay for services'), which steers the agent away from wrong expectations. It does not name the specific sibling tools to use for those excluded steps, keeping it below 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?

Beyond annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=false), the description discloses the URL's 15-minute validity, that the file is PUT directly to the returned URL, that a curl command and in-app destination page are also returned, the 25 MB cap, per-destination format whitelists, and that a vault file name must be free in its folder. What remains unsaid is permission/role requirements and whether any follow-up registration call is needed to finalize the upload.

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?

It is front-loaded with the action and destinations, then return values, then hard constraints. The sentences are long and list-heavy, but each clause (validity window, size cap, format whitelist, name-free rule) carries operational information rather than 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 two-mode tool with a nested destination object and an output schema, the description covers modes, return payload, size/format limits and naming constraints. The main remaining gap is the end-to-end workflow: whether the PUT alone completes the upload or whether register_upload must be called afterwards, plus any authorization prerequisites.

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 genuinely adds meaning: file_name uniqueness per folder, the 25 MB limit tied to content_length, allowed MIME types per destination kind, and that file contents cannot be passed as text. It stops short of giving a path syntax example beyond what the schema already shows.

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 ('Starts uploading one file to Lightbringer') and enumerates the two destination kinds with what each produces (a new drawing in an innovation's Illustrations section vs. a file in the vault). It is clear what the tool does, but it never distinguishes itself from the sibling register_upload or create_asset, which an agent must choose between.

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: the description explains what each destination kind is for, which helps an agent pick the right destination object, but there is no explicit 'use this when' / 'use X instead' guidance and no mention of how this relates to the sibling upload/register tools.

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 write, destructive, and open-world annotations, it discloses email-notification side effects, the returned updated state, and the asymmetric reversibility of the two responses. The warning that approval cannot be withdrawn through this tool is especially valuable for a consequential mutation.

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 front-load the operation and side effects, then give the usage precondition and important state-transition constraints. Every sentence contributes actionable information without repetition or unnecessary background.

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 three-parameter mutation with an output schema, the description supplies everything important for safe invocation: purpose, consent requirement, external side effect, and reversibility. It even mentions the returned state despite the output schema already being available.

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 schema already documents all three parameters and the response enum. The description adds meaningful lifecycle semantics for the response values—approval is not withdrawable here, while request_changes can later become approval—but adds little about review_id or message.

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 action and resource: recording a user's decision on a review, with the two possible decisions named. It clearly distinguishes this state-changing operation from review-reading siblings such as get_review and list_reviews.

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 explicitly says to use the tool only after the user has chosen their response, providing a meaningful consent precondition. The explanation of which response can later be changed also helps the agent choose correctly between approval and requesting changes.

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?

Well beyond the readOnly/openWorld/destructive annotations, it discloses that vault results require a connection with write scope, that document indexing is asynchronous so empties are inconclusive, and that the refresh assessment calls no provider and mutates nothing. These are exactly the caveats an agent needs before trusting or retrying a result.

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 purpose and category behaviour, and most sentences carry distinct, non-redundant information. It is dense and runs long, with a few crammed constructions (the list 'reports and Strategies'; the ambiguous 'Its refresh assessment' referring back to the family overview).

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 four-parameter, multi-category search with an output schema present, the description covers category semantics, pagination, permission prerequisites, index staleness, result shape (ID/title/summary, document parts with fetchable IDs) and the family-overview enrichment. Nothing material 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 coverage is only 50% (query and cursor documented), so the description has to carry the enum: it defines the semantics of the 'meeting' and 'vault' categories and notes that omitting query broadens to the whole category, plus that pagination is cursor-based. Only 'limit' is left entirely unexplained.

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 and resource: searches the organisation's documents, meetings and vault files, and enumerates the document kinds covered. An agent can tell this is an internal-corpus search, though it never names its closest siblings (search_public_patents, list_innovations) to sharpen the boundary.

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 explains per-category behaviour (how the 'meeting' and 'vault' categories match, that omitting query lists everything) and hints that meeting IDs resolve via fetch, which is useful routing context. It never states when to prefer this over list_* siblings or search_public_patents, so the choice is left implicit.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive behavior, and the description adds substantial context beyond them: a 25-result page cap, untrusted source data caveat, null expired/abandoned values meaning unknown, `nextPage`/`truncated` semantics, and a conditional pricing model where searches are refused once credits are exhausted.

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?

Purpose is front-loaded in the first sentence, followed by result-shape, trust caveat, and cost notes in a logical order. The text is dense with short clauses and the pricing sentence is somewhat convoluted, but no sentence is truly redundant.

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 need not explain return fields, yet it still flags `nextPage` and `truncated` as the important paging signals. Together with the trust caveat and cost model, an agent has everything needed to call this safely and correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75% and the schema already documents `query`, `assignee`, and `publicationNumber` in near-identical language. The description restates the search modes but adds no format or syntax guidance, and never mentions the `page` parameter or its 40-page ceiling; 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 ("Searches public patent publications") plus the three lookup modes (publication number, keywords, assignee). It explicitly distinguishes itself from the sibling `search` (saved organisation documents) and from `import_patent`, so an agent can identify it 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?

Names the alternatives and the boundary: searching does not import documents, and `import_patent` is the tool for importing a selected publication; it also routes cost checks to `get_credits`. It does not, however, advise which of the three lookup modes to prefer in a given situation, leaving that inference to the agent.

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 only flag readOnlyHint=false, destructiveHint=true and openWorldHint=true; the description supplies the substance behind them: the consent gate, the mcp:write permission requirement, the human-reviewed Slack destination, that the channel is invisible to the signed-in user, and that no account or client metadata is attached. It also sets expectations that delivery is one-way ('does not request professional work or promise a response or resolution') and bounds what is transmitted, which is exactly the behavioral context an agent needs before an irreversible external send.

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 the when-not-to-use constraint are front-loaded, and nearly every sentence carries a distinct obligation (consent, permission, destination, data minimization, no promised response). It is nonetheless a single dense paragraph with visible overlap: 'Only the report text, category and optional tool name are sent' is restated later as 'Reports contain only the issue or unresolved need the user agreed to share.' Slightly tighter or bulleted structuring would improve scanability.

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 irreversible external-send tool with three parameters, the definition covers the full decision surface: eligibility, consent and permission preconditions, what payload leaves the system, where it goes, who can see it, and what the agent should not promise. An output schema exists, so the absence of return-value detail is not a 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 description coverage is 100%, so the baseline is 3; the description earns above that by adding content-level meaning beyond the schema, namely how to phrase an unmet-need report (intended outcome, help provided, remaining obstacle, confirmed evidence, keep unknowns explicit) and what must be excluded (transcripts, document text, invention details). It reinforces the feedback/category/tool_name restriction but adds no new syntax or edge-case handling for maxLength or the enum values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Sends feedback the user explicitly wants to share about Lightbringer tools or customer needs the available assistance could not resolve,' and then enumerates what counts (broken/surprising behaviour, missing capabilities, friction, unresolved customer problem). That is far more specific than the title. It stops short of a 5 because it never names or contrasts the closest sibling, start_innovation_feedback, leaving the agent to infer which feedback channel applies.

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 explicit inclusion criteria (tool bugs, missing capabilities, friction, unresolved customer need), explicit exclusion criteria ('Do not infer a service-wide gap from missing access, evidence or a limitation of this conversation'; not feature proposals or solution suggestions), and hard prerequisites (user must see the report text, category and optional tool name, be told the recipient, and consent). When-to-use, when-not-to-use and preconditions are all present.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is partly covered. The description still adds real value beyond them: org-wide visibility for members and agents, the fact that existing competitor monitoring picks it up, that publication is not scheduling, that multiple strategies can be live at once, and that strategy management rights are required. It stops short of saying what is lost or who loses access when a strategy is reverted to draft, which matters given destructiveHint=true.

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 a distinct fact: the action, the effect, the negative scope (no monitoring start), the concurrency rule, and the permission requirement. Nothing is repeated and the primary action is 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?

With an output schema present, return values need no explanation, and the description covers permissions, visibility consequences, and the monitoring side-effect boundary. The remaining gap is the unwind path – what reverting to draft does to already-distributed context or downstream agent knowledge – which is relevant for a destructiveHint=true tool.

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. The description compensates by making the boolean's two states explicit (publish vs. return to draft), so an agent can map publish=true/false without guessing, though it never uses the parameter name directly.

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 pair (publish / return to draft) on a specific resource (strategy), and the title reinforces the status-change framing. It is clearly distinguishable from siblings like create_strategy, edit_strategy, and delete_strategy, which mutate content or existence rather than publication state.

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?

"On explicit user request" gives a clear usage condition, and the note that publication does not schedule or start monitoring pre-empts a likely misuse (expecting it to kick off competitor monitoring). It does not name an alternative tool for content changes, so the routing guidance is strong but not complete.

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 destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: it discloses that the whole selection is replaced (not merged), that the change resets earlier approvals to pending, and that it is gated by role and review state. Those are the consequences an agent must know before invoking a destructive write.

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 action and target are front-loaded, and the sentence order moves logically from what is set, to how, to who may change it, to what happens next. It is slightly dense and repeats the countries concept twice ('selection of countries' then 'the countries a European patent is to be validated in'), but nothing is wasted.

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 two-parameter destructive mutation, the definition covers purpose, code format, replacement semantics, authorization rules, approval side effects, and the next step. With an output schema present, no return-value explanation is needed, so nothing material 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by specifying that codes are two-letter EPC state codes or 'UP' for the Unitary Patent, which constrains the domain beyond the schema's generic pattern. review_id is left to the schema, which is acceptable given its own description.

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 and resource ('Sets the user's selection of countries on a validation review') and narrows the scope to type ENTRY_PLAN_VALIDATION with the accepted code format. An agent can distinguish this from sibling tools like get_review or respond_to_review without opening any 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 routes the agent: get_review is named for inspecting recommended and currently selected countries, and respond_to_review is named as the follow-up approval step. It also states the preconditions (review must be open, caller must be an unapproved reviewer or a specialist), which is exactly the when-to-use information needed.

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 only declare readOnly=false, destructive=false, openWorld=false; the description goes well beyond by disclosing the return payload shape, the meaning of findings_error, terminal statuses, and the non-cancellation semantics of the wait. It also surfaces a costly side effect the annotations do not capture: credit consumption tied to the clarity focus, including the refusal case for clarity-only requests and the 'not started' degradation when combined with other focuses.

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 purpose and behavior, and nearly every sentence carries distinct information (statuses, credits, exclusions). The prose is telegraphic and slightly dense, compressing several distinct ideas into semicolon-joined clauses, but there is little true waste.

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 need not restate return fields, and it still explains the status lifecycle, error semantics, and credit failure modes. For a two-parameter async-start tool, an agent has everything needed to invoke it and to know what to do next.

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 would be 3, but the description adds real meaning by unpacking the enum into human-readable focus labels and by tying the 'clarity' value to a credit charge and a possible refusal/partial-not-started outcome. It does not add anything for invention_id beyond noting the innovation must be registered.

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?

Names a specific verb and resource ('starts automated analysis of a registered innovation description') and enumerates the focus areas covered. It also explicitly distinguishes itself from adjacent capabilities (novelty assessment, patent search, FTO, attorney review, patent preparation) and points to get_task_status as the continuation path, so an agent can place it precisely among siblings.

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 explicit when-to-continue guidance ('queued or running tasks continue through get_task_status with the same task_id'), states which statuses are terminal, and notes that ending the wait does not cancel analysis. It also carves out when NOT to use it by listing the separate request types it does not handle.

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 destructiveHint=true and idempotentHint=false, and the description goes well beyond them: it discloses replace-collection semantics (omitted sections are deleted), that section IDs and comment anchors survive, that the write is atomic at the supplied revision, that stale revisions fail without writing, that edits touching pending review changes fail, that detached discussions are reported, and the required write consent and Strategy management rights. This is exactly the extra context a destructive mutation needs.

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 prerequisites, then destructive semantics, then failure modes, then permissions. It runs long at eight sentences, but nearly every sentence carries a distinct operational fact; only the trailing readback guidance borders on restating the conflict rule.

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, deeply nested destructive mutation with an output schema, the description covers provenance, atomicity, replacement semantics, permission gating, partial-failure reporting, and recovery. Nothing an agent needs before invoking it 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?

Although the reported top-level coverage is 0%, the description supplies provenance the schema cannot: revision must be asset.revision from the latest fetch with include_asset: true, and the section array is a complete desired state rather than a patch. It reinforces the delete-on-omission rule and the 'omit the field to leave unchanged' distinction, adding real meaning over the raw 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 ("Updates one asset to the supplied state") and bounds the scope ("Currently supports Strategy title and ordered Markdown sections"). It does not explicitly distinguish itself from the sibling edit_strategy, so an agent must infer which mutation path to take, but the resource and field scope are unambiguous.

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 concrete when-to-use prerequisites (input must come from fetch with include_asset: true) and when-not boundaries ("Does not publish or run a service"), plus a conflict recovery path ("conflicts require a fresh fetch and reconciliation"). It never names the alternative sibling tools such as set_strategy_publication or edit_strategy directly, which keeps it just short of fully explicit 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?

Goes well beyond the destructiveHint/readOnly annotations: it discloses the optimistic-concurrency contract (revision required, stale revisions rejected without changes), partial-update semantics (omitted fields unchanged), replacement semantics (notes replaces the whole shared text), clearing semantics (empty strings clear fields), and the return payload plus new revision.

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?

Six dense sentences, front-loaded with the action and prerequisites before edge-case semantics; every clause carries an operational fact (auth, concurrency, clearing, rename limits) with no restatement of the title or name.

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-object mutation with an output schema, it covers everything an agent needs before calling: permissions, the required revision and its failure mode, partial vs full replacement behaviour, and what comes back. Only the state/country fields lack semantics, a minor omission.

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 reported as 0% at the top level, so the description must carry meaning, and it does: it explains where revision comes from and why it matters, that notes is a full replacement, that empty strings clear fields, and the special applicant_name behaviour. The state and country fields are never given meaning in either place, which is the remaining 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?

Opens with a specific verb+resource ('Updates selected profile fields or shared assistant notes in the connected organisation') and explicitly bounds scope with 'Does not create or publish a Strategy', separating it from create_strategy and get_company_context without needing 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?

States the prerequisites ('Requires moderator rights and write consent'), names the sibling that supplies the required input ('The revision from get_company_context'), and gives one explicit exclusion (no Strategy creation/publication). It stops short of contrasting with other mutators like update_asset or update_innovation, so it is clear context rather than a full when/when-not map.

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 destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description still adds substantial behavior: omitted sections are preserved with their comment threads and pending changes, specified sections are overwritten, and each applied section reports dropped markdown, detached_threads, and marks_incomplete. The "smaller writes keep them" note explains when anchors survive the write, which an agent cannot get from 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?

Front-loaded with the core action and result shape, and no sentence is filler. The second sentence is a long parallel clause carrying several distinct behaviors at once, which is efficient but denser than ideal; it could be split for faster scanning.

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?

This is a destructive mutation on a nested-section object, and the description covers overwrite scope, omission behavior, and the per-section outcome fields, while an output schema exists so full return-value explanation is unnecessary. Remaining gaps are minor: nothing about what happens if invention_id does not exist, and the return-field naming is stated slightly redundantly against the output 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 coverage is 100% and each section field already documents full-replacement and empty-string-clears semantics, so the baseline is 3. The description adds genuinely new meaning beyond the schema: partial update via omission preserves existing text and comment state, which is not stated anywhere in the nested object 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?

"Updates one or more sections of an existing innovation record with new content and reports, per section, whether it was applied" gives a specific verb (updates), a specific resource (innovation record sections), and a scope (partial, per-section). The resource name plus per-section reporting separates it from read siblings like get_innovation and from update_asset/update_company_context without needing to name them.

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 explicit when-to-use/when-not-to-use or alternative tool is named. The clause "Text the agent leaves as read keeps its comment threads and pending changes" implicitly tells the agent to omit sections it does not want to change, which is real usage guidance, but it must be inferred rather than stated as a rule, and nothing says when to prefer update_innovation vs. register_innovation or edit_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 establish readOnly, non-destructive, closed-world behavior, so the bar is lower. The description adds real value beyond them: the member roster is bounded at 20, requires 'read consent', and a failed member lookup is reported separately from the profile rather than failing the whole call. It does not state anything about token scopes or auth failure modes.

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 with the core answer front-loaded and the optional member behavior and its partial-failure semantics following. No filler, though the final clause is dense enough to need a second read.

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 restated, and the single optional parameter is documented in both schema and description. The partial-failure disclosure closes the main ambiguity for an agent acting on the result; only auth/permission expectations are 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?

Schema description coverage is 100%, so the schema already carries include_members as a boolean for the bounded roster. The description does add meaning by naming the bound (up to 20) and the returned member fields (names, roles, total count), which is more than the schema conveys, but it stops short of useful mechanics.

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 first sentence names a specific verb and resource pair: 'Returns the signed-in Lightbringer user and organisation for this connection.' No sibling tool in the list (get_company_context, list_tasks, etc.) does identity/connection resolution, so an agent can route here unambiguously.

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 by the identity-returning purpose; there is no explicit statement of when to call this versus alternatives such as get_company_context, nor any prerequisite or exclusion. The description does clarify the optional-members branch, which is a partial substitute for call guidance.

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