Skyelight

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

Annotations cover the safety profile (idempotent, non-destructive, non-read-only), and the description adds the details annotations cannot express: the human is notified, permission roles required, and the resolved-state precondition. That is exactly the calibration example's 'credit for adding context' standard.

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

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

Three short sentences, each with a distinct payload: the action, the unassign escape hatch, then the preconditions. 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 no output schema, the description covers the side effect, permissions, and the failure precondition, which is what an agent needs to call it safely. It omits only what the response or failure looks like, a minor gap given the annotation coverage.

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 itemId's source (list_items) and assignee's accepted forms (name/email/id/'me'/null) are already documented. The description's 'pass null to unassign' duplicates the schema; only the notification consequence tied to assignee adds marginal meaning. 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 ('hand an item to a person') plus the defining consequence (the assignee is notified). No sibling tool in the list performs assignment, so this is unambiguously distinguishable from set_status, create_item, or post_update.

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

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

Gives clear operating conditions: null assignee to unassign, only owners/admins/collaborators may assign, and resolved items must be reopened first. It stops short of naming an alternative tool or an explicit 'do not use when' case, but the preconditions are strong enough that an agent knows when the call will fail.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds genuinely non-obvious context the annotations cannot express: the call executes under the connection owner's identity and is unavailable outside a personal connection. It stops short of saying whether the thread notifies anyone or what the response contains.

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, purpose front-loaded, with no filler. The second sentence is slightly indirect ('so the answer lands where the question was asked'), though that rationale does justify the alternative-tool rule rather than being decorative.

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 7-parameter mutation with strong schema coverage and no output schema, the description covers the critical unknowns: identity of the actor and the availability constraint. Minor gaps remain — whether creating a thread notifies mentioned people, and what the call returns — but nothing blocks 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 86%, so the schema already documents nearly every parameter, including the 'me' convention for assignee and mentions. The description only reinforces the identity framing ('as the person whose connection you are using'), which subtly explains what 'me' resolves to but adds little else beyond the schema. Baseline 3 is appropriate.

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

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

States a concrete verb and resource — 'Open a new thread on a page' — and immediately pins down the acting identity ('as the person whose connection you are using'). It explicitly separates itself from the sibling post_update, so an agent can route between them without opening either schema.

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

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

Gives an explicit availability constraint ('Only available on a person's own connection') and names the alternative tool with the condition that selects it ('an agent reporting what it found or changed uses post_update on the thread it was working'). That is a complete when-this/when-that routing rule.

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, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results are quoted with their conversation, and the response includes the project's existing rules so the agent can distinguish new decisions from known ones. Pagination behavior is left to 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?

The content is front-loaded and reasonably short, but the middle clause ('plus types people corrected and where outcomes keep recurring') is convoluted and hard to parse on first read. One sentence carries too many bundled ideas, costing clarity for little concision gain.

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 output schema, the description takes on the job of describing return content, and it does so at a high level (quoted decisions with conversation, plus existing rules). The vaguer clause about 'types people corrected and where outcomes keep recurring' leaves the exact shape of that portion underspecified, but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so limit, since, offset and projectId are all documented in the schema, including the 'more' line convention for offset. The description adds no additional parameter meaning, 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?

The description states a specific resource (resolved/deferred decisions from a project's threads, with quoted conversation) and adds that it also returns existing rules. It's clearly a read/aggregation tool distinguishable from list_items or search_items, though the naming of the verb is implicit ('The decisions a project made') rather than an explicit 'returns X'.

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 two concrete use cases ('to write a decision log', 'to find rules worth keeping') and names the downstream sibling save_rule, so the agent knows the follow-up action. It stops short of exclusions — nothing says when to use search_items or project_review instead.

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, non-destructive, closed-world behavior. The description adds real context beyond that: results are ordered by line proximity, the no-arg mode ranks all stamped files by outstanding feedback, and data comes from build-plugin stamping. It does not discuss result shape or pagination, which is a modest gap for a read tool.

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

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

Two tight sentences with no waste, front-loading the data source and then the two operating modes. Every clause earns its place, and the no-arg behavior is stated immediately after the primary mode.

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 six-parameter, zero-required query tool with no output schema, the description covers the main selection axes and ordering semantics well. The remaining gap is that limit and status filters are left entirely to the schema, which partially documents the other parameters but not these two.

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 a moderate 67%, so the schema carries much of the burden. The description usefully explains the file/component alternatives and the meaning of passing neither, but it says nothing about the limit or status parameters, which are undocumented in both schema and 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?

The description pins down a specific resource (feedback threads tied to the source file/line stamped by the Skyelight build plugin) and clearly separates the file/component lookup mode from the no-argument hot-spot mode, which differentiates it from generic siblings like search_items. It lacks an explicit verb, opening with a noun phrase, but the intent is 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?

It gives clear usage conditions: pass a file or component to review threads 'before you edit it', and pass neither to get the hot spots. It does not name alternatives or exclusions (e.g., when to prefer search_items or find_similar instead), so it stops short of full 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds value beyond that by describing the result shape and rationale — matches are returned with 'why each matched: shared words, same page, same element, same source file' — which tells the agent how to interpret and justify the results. It stops short of covering cost, latency, or ordering of matches.

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 doing distinct work: the question, the two call modes, the return semantics, and the follow-up tool. The primary use case (pre-create duplicate check) is front-loaded in the first clause, and nothing is repeated from the schema or annotations.

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

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

There is no output schema, yet the description still explains what comes back and why, and annotations carry the safety profile for a read-only, idempotent lookup. For a 7-param optional-arg search tool with full schema coverage, an agent has everything needed to call it and act on the result.

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 intent beyond the schema: text is 'what you are about to report', page is optional context, and itemId is the mutually exclusive mode for locating duplicates of an existing thread. The limit, includeResolved, selector and projectId parameters are left entirely to the schema, which caps this below 5.

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 the question the tool answers ('Has this already been reported?') and then states a concrete verb+resource: find likely matches for a report text or an existing item. It explicitly separates itself from create_item (call before) and merge_items (call after), so an agent can route 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?

It gives an explicit when: before create_item, and with the text you are about to report, optionally with the page. It also names the alternative mode (pass an itemId to see what a thread duplicates) and the downstream action (merge_items folds one into the other), so the full decision path is spelled out with no inference required.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context that the thread is ordered and pictures are returned as viewable images rather than links, though it omits limits, permissions, and error behavior.

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

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

Front-loads the purpose and packs return details into a single sentence with little filler. The em-dash-heavy structure and editorial 'links you cannot' phrasing slightly reduce scanability, but the information mostly earns its place.

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

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

With no output schema, the description must carry the return shape, and it covers the thread, page URL, anchor, pinned screenshot, and attachments. It does not describe failure behavior or any limits, but it is adequate for a simple read-only get.

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

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

The sole itemId parameter is fully documented in the schema, including its source from list_items. The description adds no additional syntax or format meaning beyond the schema, so the high-coverage 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?

Names the specific resource and scope ('one item') and enumerates the returned contents: thread, page URL, anchor, and images. It is distinguishable from list_items through the one-item focus and the itemId source, but it never uses an explicit retrieval verb or directly differentiates from search/find 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?

Provides only an implied usage cue: itemId comes from list_items, and 'work one item' suggests fetching full detail. It does not explicitly say when to use this tool versus search_items or find_similar, nor when not to use it.

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, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuinely new context: it returns a project summary alongside items, and it discloses a binding workflow rule (on investigate/plan, reply on thread and change no code) that no structured field carries.

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

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

Three sentences, front-loaded with purpose then return shape then routing advice, with no filler. The final hand-off sentence is somewhat tangential to a listing call but earns its place by preventing downstream misuse of the returned data.

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 seven-parameter, all-optional listing tool with no output schema, the description covers purpose, return contents, and an entry-point recommendation, while annotations cover safety. Ordering of results and pagination behavior beyond the limit parameter are the only notable gaps.

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%, including enum semantics for task and status and the 'me'/'none' assignee convention, so the schema does the heavy lifting. The description adds nothing parameter-specific beyond implying filtering, which lands at the baseline.

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 ('List feedback items (bugs, ideas, comments)') plus the scope ('on a Skyelight project') and the return shape ('summary of the project plus matching items'). It does not name or contrast with the sibling search_items, so an agent must infer when this differs from searching.

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?

'Start here to see what is outstanding' gives a clear entry-point cue for the tool's primary use. It stops short of explicit exclusions or naming alternatives such as search_items or get_item for a single item.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds the shape of the returned records (name, email, role, id), which matters since there is no output schema, but says nothing about scoping behavior when neither projectId nor workspaceId is supplied, or about result size/limits.

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 returned-field summary front-loaded, followed by a usage clause with concrete downstream consumers. The second sentence is a run-on chain of clauses ('tell, ask or hand... then pass... or in mentions on...') that could be tighter, but it carries 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-optional-parameter read tool with no output schema and full annotation coverage, the definition supplies the missing return shape and the chaining guidance an agent needs to act on results. The main residual gap is what happens when neither scope parameter is provided.

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 both optional parameters documented in the schema, including the 'Optional if a project is bound' fallback logic for projectId. The description adds only the general workspace framing and no extra syntax or precedence detail, 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 names the resource ('The people in a workspace') and enumerates the returned fields (name, email, role, id), which makes the tool's job concrete even though the verb 'list' itself is implied rather than stated. It is distinguishable from siblings like list_projects or list_workspaces by the workspace-members framing.

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 clear trigger ('when you are asked to tell, ask or hand something to someone by name') and routes the agent downstream to assign, create_item mentions, and post_update mentions, naming actual siblings. It omits any when-not guidance (e.g., use search_items for finding items instead of people), which keeps it just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavior: result ordering by newest activity and the default of spanning all workspaces when no workspace is named. It does not mention pagination or result size limits, which is the only meaningful 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?

Two sentences, zero filler. Scope and ordering come first, then the routing rationale for why to pick this tool over jumping into list_items.

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?

There is no output schema, yet the description conveys enough about the result set (project entities, ordered by newest activity, spanning workspaces) for an agent to use the output correctly. Missing only volume/pagination characteristics and what identifying field the returned project id is named.

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 self-documenting, so the baseline is 3. The description adds real semantic value by stating the default behavior when the parameter is omitted ('across every workspace unless one is named'), which the schema only weakly implies with 'Optional.'

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 the resource (projects), the scope (everything you can reach, across every workspace), and the ordering (newest activity first) in a single front-loaded clause. It also implicitly distinguishes itself from list_items by noting that list_items needs a project id that this tool supplies.

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 states the triggering condition ('Start here when no project is bound') and names the concrete downstream dependency ('list_items needs a project id and this is where one comes from'). An agent knows both when to call it and why, without consulting siblings.

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, idempotent, non-destructive, so the safety profile is settled. The description earns credit for disclosing the shape of the result (per-workspace role and the caller's identity), which the annotations cannot convey, especially since there is no output schema. Pagination or scale behavior is unstated.

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, front-loaded with what is returned before the when-to-use clause. The trailing 'and who you are' is slightly awkward phrasing but carries real information about the returned identity field.

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 output schema and no parameters, the description carries the burden of explaining the return value, and it does describe the key fields. It stops short of a 5 because the exact keys, ordering, or result size are not hinted at.

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?

Zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly signals that no input is needed by framing it as a discovery 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?

Names the resource (workspaces) and states the content returned: the role held in each plus the caller's own identity. That goes beyond a restatement of the title. It does not explicitly distinguish itself from siblings, though none of the named siblings are workspace-listing tools.

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

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

Gives three concrete situations to reach for it: when you don't know what exists, when you need to map a project to a workspace, and when you need your own user id. No exclusions or named alternatives are given, so it stops short of a 5.

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

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

Annotations already mark this tool as destructive and non-idempotent, but the description adds concrete semantics: duplicates leave the list, count as extra reports on the kept item, and lists the permitted roles. This is meaningful behavioral context beyond what annotations provide.

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

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

Three sentences, front-loaded with the effect, then the usage condition, then permissions. Every sentence earns its place, and the app analogy is compact and useful.

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 only two fully documented parameters, rich annotations, and no output schema, the description gives enough to call the tool correctly: prerequisite, effect, and authorization are all covered.

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 explains that itemId is the item to keep and duplicateIds are items reporting the same problem. The description restates the fold-into relationship but adds no syntax, constraints, or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('Fold duplicate items into one') plus the concrete outcome of the merge. It clearly separates this action from the discovery sibling find_similar, which is framed as a prerequisite rather than the same operation.

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 constrains use to cases where find_similar and the threads show the items are the same problem, and states who can merge. It does not spell out an alternative action for non-duplicates, so usage is clear but not fully explicit about alternatives.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation. The description adds the key behavioral fact beyond that: the post appears as a reply on the original feedback thread, so the reporter is the audience. It omits retry/duplication behavior, which matters for a non-idempotent write, so it falls short of a 5.

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

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

Three short sentences, front-loaded with the purpose, followed by effect and timing. The audience rationale is stated twice (description plus schema), a minor redundancy that doesn't meaningfully bloat it.

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

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

For a simple write tool with full schema coverage and no output schema, this covers what an agent needs: what to write, where it lands, and when to invoke it. The remaining gap is idempotency/duplicate-post risk, which an agent should know before retrying.

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 every parameter is already documented including 'itemId from list_items' and the mentions formatting convention. The description only echoes the body content already in the schema, adding no syntax or constraint detail beyond it, which is the baseline case.

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

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

States a specific verb and resource ('report back on an item') and enumerates the content types it accepts (findings, changes, PR link). It implicitly distinguishes itself from siblings like set_status or create_item by framing itself as a report/reply rather than a state change, though it never names those 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?

'Use this when you finish work on an item, and when you get stuck' gives clear triggering conditions, including a non-obvious one (blocked state). It does not state exclusions, e.g., whether status changes belong here or in set_status.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: each entry carries an item id for traceability, and it warns 'Quote; do not invent outcomes the threads do not state.' It also briefly describes the return shape. These additions go beyond the annotations and aid correct use.

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

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

The description is a dense but well-structured paragraph, front-loading the overall purpose and then detailing content and a caution. Every sentence contributes: purpose, content delineation, traceability, and usage guidance. It could be slightly more concise, but it avoids fluff.

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?

Without an output schema, the description does a thorough job explaining what is returned: the shape of work, resolved threads with outcomes, deferred items with reasons, open items, and quoted conversations. It also mentions traceability and a quoting rule. Minor gaps (e.g., pagination behavior) are covered by the input schema's offset parameter, making this nearly complete.

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

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

Schema coverage is 100%, so parameter meanings are fully defined there. The description reinforces the section-based content (resolved, deferred, open, discussions) but does not add syntax or format details beyond what the schema already provides. Baseline 3 is appropriate when 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?

The description clearly states the tool provides a complete package for writing a project review or hand-off, enumerating the included sections. It names the resource (project review) and the value (accurate, traceable). However, it does not explicitly differentiate from siblings like decision_log or get_item, leaving a small gap.

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 'Everything needed to write an accurate project review or hand-off document,' but there is no explicit guidance on when to choose this tool over alternatives or any exclusions. The schema's section enum provides some direction on how to use parameters, but the description itself is vague about when to use this tool.

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

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

Goes well beyond the annotations: discloses that republishing with the same prototypeId or name creates a new version at the same link (clarifying the idempotentHint=false semantics), that a hosted link is public to anyone holding it, that permissions are owner/admin, and that the url mode mutates the project's Review Links. It also defines the return values ('the share link and the project link') that no output schema provides.

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 outcome, then cleanly organized into the two bulleted modes; nearly every clause carries real decision-relevant information. The code bullet is dense with parenthetical caveats (Tailwind, npm imports, local imports fail) that are necessary but make it heavier than ideal.

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 8-parameter, zero-required, write-scoped tool with no output schema, the description covers all the gaps an agent would otherwise hit: which param combination to pick, what comes back, what to do with the result, permission level, and visibility of the artifact.

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; the description earns more by explaining cross-parameter behavior the schema can't: code and url are alternatives, prototypeId republishes a prior prototype under the same link, and an omitted projectId creates a new project (with workspaceId only relevant in the multi-workspace, no-project case).

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

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

States a specific verb and resource: share a file or deployed app with Skyelight for review and get a feedback link. It immediately splits into the two distinct modes (code vs url) so an agent knows exactly what artifact it produces, and nothing among the siblings (assign, create_item, project_review, post_update) overlaps.

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 when-to-use routing: use 'code' for Claude prototypes, v0 snippets and single pages; use 'url' for anything with more than one file already deployed (Lovable, v0, Bolt, Vercel). It also states the prerequisite ('Owners and admins') and the post-call step for the url mode (add the script tag to <head> and redeploy).

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

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

Goes well beyond the annotations by explaining the effect of the write: the rule lands in project context under 'Rules learned', the classifier reads it, and agents see it via decision_log, shaping future threads. It also discloses the permission requirement and the human-confirmation expectation, which the annotations cannot convey.

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

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

Front-loads the action and storage location, then layers in downstream effects and the permission/confirmation caveat. Each sentence carries information, though the density of clauses makes it slightly heavier than needed.

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 annotations covering safety/idempotency, a fully documented 3-parameter schema, and no output schema, the description supplies everything an agent needs: persistence target, who can call it, downstream impact, and the pre-save confirmation norm.

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. The description's 'cite the threads it came from' loosely reinforces sourceItemIds and the 'project's context' phrase hints at projectId, but neither adds format or constraint detail beyond the schema.

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

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

States a concrete verb and resource ("Keep a rule ... in the project's context, under Rules learned") and grounds it with two example rules, so an agent can distinguish it from reads like decision_log and from item-creation tools. The storage location and downstream consumers are named explicitly.

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

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

Gives clear operational context: cite the source threads, restrict to workspace owners/admins, and confirm with the person before saving. It implies the alternative (decision_log is the read path) but does not explicitly say when *not* to save a rule versus other options.

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, idempotent, non-destructive, so safety needs no restating. The description does add one genuinely useful behavioral fact: matching spans replies as well as the original message, widening recall beyond the top-level body. It says nothing about result ordering, whether matches are ranked or truncated, or how the limit is applied.

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, front-loaded with the core action and followed by the one behavioral nuance that matters. The 'already diagnosed in a reply' clause earns its place by concretely illustrating the recall behavior rather than padding.

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?

There is no output schema, so the description must carry all expectations about results, and it does not say what a match returns, whether ordering is by relevance or recency, or how limit and status shape the page. Adequate for the matching semantics, thin for anything an agent needs to interpret the response.

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 projectId are documented in the schema, while limit and status carry no description anywhere. The description does not mention any parameter, so the two undocumented ones (including the status enum's effect on results) get no compensating explanation.

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 ('Find') and resource ('items') plus the matching scope: text appearing anywhere in the item's thread, including replies. That is enough to separate it from list_items or get_item, though it never names a sibling to sharpen the distinction from find_similar or find_by_source.

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

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

The phrase 'whose thread mentions some text' implies keyword search, which lets an agent infer it is not the tool for a known item id (get_item) or an exact source lookup (find_by_source). But there is no explicit when-to-use statement, no exclusion, and no guidance on when find_similar is the better 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 declare idempotent, non-destructive, non-read-only, so the safety profile is covered; the description adds workflow-level behavior such as the required ordering with post_update. It does not say what happens when the item is already in that state (tap on the idempotentHint) or whether the reporter is notified, which keeps it below 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?

Front-loaded with the action and the allowed statuses, then the workflow rule, then the edge-case semantic. The trailing quoted-'deferred' clause is slightly clipped and reads as an afterthought, 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?

A 2-parameter mutation tool with no output schema and annotations covering reversibility/isolation; the description covers ordering and status semantics well. Remaining gaps (no-op behavior on repeat calls, any side effects on the reporter) are modest but not trivial for a status-changing operation.

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

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

The schema documents itemId (from list_items) but leaves the status enum bare; the description supplies the meaning of 'deferred' and implicitly frames 'resolved' as closing the loop. That adds real semantic value over the bare enum, though 'open' is left uninterpreted.

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

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

States a specific verb + resource ('Move an item to...') and enumerates the exact target states, so the agent knows this mutates status and which values are possible. The intended moment of use (after a fix has been communicated) further separates it from siblings like post_update or assign.

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 sequencing guidance — post_update first, then set_status — with the rationale (the reporter reads what changed), and clarifies that 'deferred' means real-but-not-now rather than dropping work. That is when-to-use and how-to-order guidance an agent cannot derive from the 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 declare readOnlyHint=false and idempotentHint=false, which is counterintuitive for a "what's new" read; the description resolves this by disclosing that a call without `since` mutates the bookmark and advances it, while `since` leaves it untouched. That is a state-changing side effect made visible, not restated.

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, no filler: what it returns, when to call it, then the since/bookmark fork. Front-loaded with the payoff and the branch condition comes before the agent needs it.

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 output schema, the description carries the return-value burden and does enumerate the result categories. Gaps are minor: no ordering, pagination, or volume expectations for what could be a large diff.

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 param definitions already carry their own weight; the description adds the interaction semantics — bookmark read-and-advance versus fixed window — that no single field description conveys. It adds modest extra value on `projectId` binding beyond the schema's 'optional if a project is bound'.

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 resource-level question ('what changed on a project since you last looked') and enumerates the payload: new threads, replies grouped by thread, resolutions/defers, assignments and mentions. No sibling tool overlaps this diff-style read, so it's trivially distinguishable.

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?

"Call it at the start of a session" gives an explicit trigger condition, and the second sentence draws the since-vs-bookmark decision boundary with the consequence of each choice. That is exactly the when-to-use guidance an agent needs.

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