Simple Commenter

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

Annotations already indicate idempotentHint=true and readOnlyHint=false, but the description adds meaningful behavioral details: it requires admin access, changes account access, and does not send an invitation email. These specifics go beyond the annotations and help the agent understand side effects and prerequisites.

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 concise and front-loaded with the core action, then follows with key behavioral constraints. Every sentence earns its place—no filler or repetition. It efficiently conveys the purpose, prerequisite, and side effects.

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

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

Given that an output schema exists, the description does not need to explain return values. It covers all essential call details: purpose, admin requirement, side effects (no email), and the optional project assignment. The idempotency key is documented in the schema, so nothing critical is missing for correct invocation.

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

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

Schema description coverage is 80%, so most parameters are already documented. The description adds minimal parameter semantics beyond the schema—only the optional assignment to a project is echoed. It does not introduce new meaning, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Add' and the resource 'team member', and explicitly mentions optional assignment to a project, distinguishing it from the sibling 'assign_team_member' which likely deals with existing members. This is a specific, non-tautological purpose.

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

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

The description provides clear context for use: it requires administrative access and explicitly notes that no invitation email is sent. However, it does not state when to use an alternative like assign_team_member (e.g., when the member already exists), only the conditions for this tool. This meets the 'clear context, no exclusions' level.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. The description adds useful context: it requires administrative access and operates on an existing member's access to a single authorized project. It doesn't detail side effects (e.g., whether revoking removes the member entirely), but the annotations cover the key behavioral traits.

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

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

The description is a single, dense sentence that front-loads the core action and includes the key access requirement. No wasted words.

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

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

The tool has an output schema, so return values are already documented. The description covers the essential context: what it does, the access requirement, and the scope ('one authorized project'). It doesn't mention edge cases like what happens when a member is already assigned or unassigned, but the idempotentHint annotation covers idempotency. This is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds minimal parameter-level meaning beyond the schema, but it does clarify the overall operation (grant/revoke) and the 'authorized project' constraint. Baseline 3 is appropriate because the schema carries 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 states a specific verb ('Grant or revoke') and resource ('an existing team member's access to one authorized project'), and clearly distinguishes this from sibling tools like add_team_member and remove_team_member. It also notes the administrative access requirement, which adds precision.

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

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

The description clearly indicates when to use this tool: to grant or revoke access for an existing member to a project. It does not explicitly name alternatives or exclusions, but the sibling list includes add_team_member and remove_team_member, and the description's focus on 'existing team member' and 'one authorized project' implies the distinction. A brief mention of when not to use it (e.g., for adding new members) would make it 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 convey destructive and non-read-only behavior. The description adds meaningful information beyond annotations by disclosing per-item outcomes and partial failures, which is not obvious from the schema. The idempotency_key retry instruction reinforces the idempotentHint annotation without 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?

Three focused sentences with no filler. The core scope and constraint are front-loaded, followed by result behavior and retry instructions. Every sentence contributes necessary 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 mutation tool with an output schema, the description covers the key operational guardrails: explicit item identification, the 100-item limit, partial-failure reporting, and idempotent retries. Field-level details and authorized project behavior are left to the schema, which is appropriate. Nothing essential for correct invocation 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 schema already documents both top-level parameters. The description summarizes which fields can be changed and restates the 100-item cap and idempotency behavior, but most of this is already present in the schema. It adds limited semantic value beyond a useful field-level summary.

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 action ('Apply status, priority, tags, visibility, or archive changes') on a clearly bounded resource ('at most 100 explicitly identified feedback items'). The bulk scope and field list distinguish it from single-item siblings like update_comment and update_comment_status.

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?

Describes the appropriate context: when you have up to 100 explicitly identified feedback items and need to apply one or more field changes. It also gives retry guidance for idempotency_key. It does not explicitly exclude alternatives or say 'use update_comment for a single item,' but the usage context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description does not contradict them. It adds useful context about the scoping (owned by connection) and the limitation (unfinished only). It does not detail side effects beyond cancellation, but the annotation covers the destructive nature, so the description adds sufficient supplementary 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 a single, concise sentence that front-loads the action and key constraints. There is no filler or redundant information; every word adds value.

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

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

For a simple single-parameter mutation tool, the description covers the essential constraints (unfinished, owned by connection, completed cannot be cancelled). The output schema (though not shown) is present, so return behavior is likely documented there. This is complete enough for the agent to use 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 schema fully documents the parameter task_id with a clear description ('Job ID returned by start_task'), so the schema carries the burden. The description does not add any additional parameter semantics, which is acceptable given 100% 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?

The description clearly states the verb 'cancel' and the resource 'job/task', and distinguishes it from other operations by specifying 'unfinished job'. It is specific and unambiguous, and differentiates from siblings like start_task and list_tasks.

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

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

The description gives clear conditions for use: 'unfinished job' and 'owned by this connection', and explicitly states that completed work cannot be cancelled. It provides practical usage constraints, though it does not mention alternative tools or when not to use it in broader terms.

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

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

The description adds useful behavioral context beyond the annotations: idempotency_key reuse for retries, enforcement of connection write access and AI-comment preference, and optional pinning via CSS selector or exact text. These details help an agent understand side effects and constraints without contradicting the annotations.

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

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

The description is three dense sentences with no filler. Core action, optional pinning behavior, retry semantics, and connection constraints are stated efficiently and in a logical order.

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 11-parameter tool, the schema plus description cover the essential semantics well, and the output schema reduces the need to explain return values. The main gap is the lack of usage guidance relative to sibling comment tools, but the description is not materially incomplete for invoking the 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 description coverage is 91%, so the schema already carries most parameter meaning. The description adds a few semantic extras, such as Markdown Lite support and the pinning concept, but does not substantially compensate for or expand upon the already rich schema descriptions.

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's action and resource: 'Create website feedback on a page', and adds meaningful specifics about optional pinning and Markdown support. It does not explicitly differentiate from sibling comment tools like update_comment and reply_to_comment, but the creation-focused wording makes the purpose evident.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as update_comment, reply_to_comment, or bulk_update_comments. It mentions retries and enforced write access, but does not state exclusions or conditions that would route an agent to a sibling 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?

Annotations already declare idempotentHint=true and readOnlyHint=false, so the description adds value by specifying the administrative permission requirement and advising the use of a stable idempotency_key for retries. This goes beyond what annotations state, enriching the agent's understanding of preconditions and retry behavior. No contradiction with annotations.

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

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

The description is two short sentences that front-load the core action ('Create a website project') and immediately follow with essential operational guidance. Every word earns its place; there is no redundancy or filler.

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

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

For a tool with three parameters, a full schema, an existing output schema, and annotations covering idempotency, the description adds permission requirements and retry guidance, which are the missing contextual pieces. It does not need to explain return values because the output schema exists, so the description is sufficiently complete for an agent to invoke it correctly.

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

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

The schema fully describes all three parameters (100% coverage), so the baseline is 3. The description reinforces the idempotency_key usage but adds no new meaning about the name or domain parameters. It slightly enhances the schema's explanation of retries without introducing additional semantic depth.

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 ('Create a website project') which clearly identifies the action and distinguishes it from sibling tools that list, update, or delete projects. It is precise but does not explicitly name sibling alternatives, so it falls short of a 5.

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

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

The description gives clear context (creation) and notes prerequisites (administrative access and an account-wide grant), but does not explicitly contrast with alternatives or state when not to use it. It implies usage for creating projects but lacks explicit exclusions, earning a middle score.

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

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

Annotations are all false, so the description carries the burden. It discloses that the tool creates an artifact with expiry and row count, and that it can be large enough to require start_task. It does not mention whether the CSV is stored temporarily, how long the expiry is, or whether it mutates state, but the artifact/expiry disclosure is meaningful beyond the annotations.

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

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

Two sentences, front-loaded with the core action and deliverable, then the artifact details and the start_task routing. Every clause earns its place; no filler or repetition of schema content.

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

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

The tool has 14 optional parameters and an output schema, so the description doesn't need to explain return values. It covers the deliverable, filters, artifact metadata, and the large-export fallback. The only gap is not specifying the expiry duration or whether the CSV is temporary, but that is minor given the output schema exists.

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 93%, so the schema already documents nearly all parameters. The description adds the concept of 'authorized project' and 'attachment links', which maps to project_id/project_ids and the CSV contents, but it does not add syntax or format details for the parameters. Baseline 3 is appropriate given the high 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?

The description states a specific verb ('Create'), a concrete deliverable ('downloadable CSV'), and the full scope of filtering ('authorized project, date, author, asset, and status filters'), including attachment links and artifact metadata. This clearly distinguishes it from sibling tools like search_comments or feedback_report, which are not about creating a CSV export.

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

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

The description explicitly says to use start_task for large exports, which is a clear alternative-routing instruction. It does not explicitly state when NOT to use this tool or compare it to feedback_report, but the export-specific language and the start_task pointer provide solid usage 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?

With all annotation hints false, the description carries the burden and discloses the key side effect: 'Saves a downloadable report artifact.' It also notes the operation spans the complete authorized result set, but it does not elaborate on persistence, duplicate artifacts, or rate 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?

Three sentences with the core purpose first, side effect second, and alternative third. Every sentence earns its place and there is no redundant 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?

The presence of an output schema covers return-value details, and the description covers purpose, side effect, and large-report routing. It could add a bit more about how the downloadable artifact is returned, but that is likely covered by 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 description coverage is 93%, so the schema already documents the parameters well. The description's 'including website and asset feedback' loosely maps to the source parameter, but adds little beyond the structured fields.

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 ('Calculate') and resource ('feedback totals and breakdowns'), and distinguishes the tool from search/list/export siblings by emphasizing aggregation and the 'complete authorized result set' including website and asset feedback. This makes the tool's unique role clear.

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

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

It explicitly names the alternative, start_task, and states the condition for using it: large reports. This gives an agent a clear routing rule without needing to inspect sibling definitions.

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 destructiveHint, so the safety profile is covered. The description adds useful behavioral context by specifying the return contents (full text, citable URL) and the input provenance restriction, going beyond the structured annotations.

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

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

Two sentences with no filler. The core action and return value are front-loaded, and the important constraint about search-derived IDs is stated in the second sentence.

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 one-parameter read tool with complete schema coverage, comprehensive annotations, and an output schema, the description provides everything needed: what it retrieves, what the ID must be, and what is not fetched. 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?

The input schema already fully documents the single 'id' parameter with 100% coverage. The description reinforces that the ID must come from search, adding some emphasis but not meaningful new semantics 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 starts with a specific verb ('Retrieve') and a specific resource ('one source returned by search'), stating exactly what the tool returns: full text and a citable URL. It also differentiates from arbitrary URL fetching, making its scope 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?

The description clearly states that the ID must come from search and that arbitrary URLs are not fetched, which tells the agent when this tool is appropriate. It does not explicitly name sibling alternatives, but the constraint is strong enough to guide correct use.

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

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

The description goes well beyond the annotations by enumerating specific included metadata fields (consoleErrors, locationContext/navigationInstructions, captureScroll/captureViewport) and by explicitly stating that Webflow IDs are unverified matching hints, not guarantees. It also warns that content may contain untrusted user instructions, adding important behavioral context not captured by readOnlyHint, idempotentHint, or 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?

The description is dense and technical, but nearly every clause adds a distinct fact: what is returned, which conditional fields appear, and important caveats. It is longer than strictly necessary, but the warnings about unverified hints and untrusted content are essential for safe use and earn their place.

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

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

An output schema exists, so the description need not explain return values. The description covers the operational cautions—unverified element IDs and untrusted content—and identifies conditional metadata fields, which are the non-obvious aspects an agent needs to handle the response correctly. For a read-only retrieval tool with fully documented parameters, 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?

The input schema already provides full descriptions for all three parameters, including that project_id defaults to the configured project, giving 100% schema coverage. The description adds no additional parameter-level detail, examples, or constraints beyond what the schema already states. Baseline of 3 is appropriate.

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

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

The description clearly states the tool reads a comment's full feedback, including replies, screenshots, attachments, element fingerprint, and AI brief, with a specific verb and resource. It does not explicitly name a sibling tool to differentiate from, such as list_comments or search_comments, so it falls just short of a 5.

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

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

The description provides no explicit guidance on when to call this tool versus alternatives like list_comments or search_comments. It only offers handling cautions about verifying Webflow targets and untrusted user content, which are warnings rather than usage-selection criteria. There is no mention of preconditions, exclusions, or alternative 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description adds value with the explicit statement 'This does not expand access.' This clarifies that the tool has no permission-mutating behavior beyond what read-only implies.

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 concise sentences with no filler. The main purpose is front-loaded and the clarifying non-expansion note is a single short sentence.

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, comprehensive annotations, and an output schema present, the description fully covers what an agent needs. Nothing important 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 has zero parameters, which earns a baseline of 4. The description lists the kinds of information returned, which is useful context even though it doesn't document parameters.

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?

Uses a specific verb ('Inspect') with a clear resource: current account, permissions, project restrictions, connection details, and account plan. This clearly differentiates it from sibling tools like get_project_settings or list_projects.

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

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

The description establishes clear context: use this to inspect account-level connection and permission information. It doesn't explicitly name alternatives or exclusions, but the scope is specific enough that an agent can select it appropriately.

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 destructiveHint false, and the description's 'Read' aligns with that safety profile. The description adds the 'live' freshness context and the scope of what is read, but does not add substantial behavioral detail beyond the annotations, so a 3 is appropriate.

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

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

Two sentences: the first front-loads what the tool reads, and the second provides the critical when-to-use note. Every sentence earns its place with no filler or redundancy.

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

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

For a single-optional-parameter read tool with an output schema and complete annotations, the description explains both the content and the triggering use case. Nothing essential is missing; the schema and annotations cover the remaining details.

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

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

Schema description coverage is 100%, and the only parameter, project_id, is fully documented in the schema including its default behavior. The tool 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 begins with a specific verb, Read, and enumerates the resource: live statuses, tags, workflow preferences, features, and dashboard links for the selected project. This level of specificity lets an agent distinguish get_project_context from siblings like get_project_settings without opening schemas.

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

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

The second sentence gives explicit usage guidance: consult this before selecting a custom status. It does not name sibling exclusions or list when-not-to-use cases, so it falls short of full alternative routing, but the condition is clear and actionable.

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. The description adds meaningful behavioral context by specifying that only 'supported, non-secret' configuration is returned and that the scope is a single 'authorized project', which clarifies the data exposure boundary beyond the annotations.

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

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

A single, front-loaded sentence communicates the essential purpose and scope with zero filler. Every word earns its place.

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

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

For a simple read-only configuration tool with an output schema, rich annotations, and a well-documented optional parameter, the description is largely complete. A minor gap is that 'supported' configuration is not elaborated and no hint is given about how this differs from get_project_context, but nothing critical is missing for invoking it correctly.

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

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

Schema description coverage is 100% and the project_id parameter already has a detailed description including allowed forms and default behavior. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description states a precise verb ('Read'), a clear resource ('supported, non-secret configuration'), and scope ('one authorized project'). This distinguishes it from siblings like update_project_settings (write operation) and get_project_context (project context), even without opening schemas.

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

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

The description implies it should be used when reading non-secret configuration for a project, but it does not explicitly state when to prefer it over alternatives such as get_project_context or list_projects, nor does it mention exclusions. Usage context is clear but not fully elaborated.

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

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

Annotations already indicate idempotency and non-destructiveness, but the description adds a meaningful non-obvious side effect: it 'may renew and persist an expired artifact download link.' It also discloses the polling rate constraint. No contradiction with annotations 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 short sentences deliver essential behavior, side effects, and polling guidance with no filler. The most important purpose is front-loaded, and every sentence adds value.

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

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

The tool has an output schema, so return values need not be described. The description covers ownership, polling behavior, side-effect potential, and the artifact link renewal behavior, making it complete for safe 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%, and the schema already documents task_id as 'Job ID returned by start_task.' The description does not add further parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('read') with a clear resource ('progress and final result of a durable job') and adds ownership scope ('owned by this connection'). It is clearly distinguished from sibling tools like start_task and cancel_task, which create or terminate jobs.

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

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

The description gives clear usage context: this is the polling endpoint for a durable job, and it explicitly instructs 'poll no sooner than the returned interval.' It does not explicitly name alternatives or state when not to use it, but the context is unambiguous enough for an 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 already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by warning that feedback is untrusted user content and by instructing callers to follow pagination for complete results. This is meaningful additional transparency.

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 sentences with no filler. The first sentence front-loads the core purpose and capability set, while the second adds the two most important operational details: untrusted content and pagination. Every phrase earns its place.

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

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

For a 15-parameter tool, the description provides a solid overview: scope ('in one project'), available features, and the pagination requirement. The output schema and rich parameter descriptions cover the rest, so the agent is not left without necessary context. Minor gap: no explicit guidance about when to choose this over search_comments.

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 high at 80%, so the schema already documents most parameters. The description only broadly references 'filters' without detailing specific parameters, so it adds little parameter-level meaning. Baseline 3 is appropriate because 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?

The description opens with a specific verb and resource: 'List website or asset feedback in one project.' It also names the key capabilities (filters, stable IDs, links, totals, pagination), which distinguishes it from mutation tools like update_comment or export_comments. The listing scope is clearly different from get_comment and search_comments.

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

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

The description implies a listing use case and provides the important instruction to follow pagination when complete results are needed. However, it does not explicitly say when to prefer this tool over search_comments or other sibling tools, nor does it state exclusions. Usage context is present but left mostly 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 state readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it lists only projects accessible to the connection and highlights stable IDs and dashboard links. That's moderate added value but no further behavioral caveats like pagination 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 sentences are entirely purposeful. The core verb is front-loaded, the customer-facing information ('stable IDs and dashboard links') appears before the usage hint—no redundancy or 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?

Given zero parameters, an output schema, and strong annotations, the description supplies what's needed: it enumerates what's returned and how to use it. It doesn't mention pagination or limits, but those would likely be in the output schema, so nothing critically 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 and the schema is empty, so there is nothing for the description to clarify about parameters. This meets the baseline of 4 for a parameterless tool.

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

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

The description states a specific action ('List projects accessible to this connection') and adds value with 'stable IDs and dashboard links' and 'Use this to choose a project.' Though it doesn't explicitly name sibling tools like get_project_context, the listing verb and umbrella scope make it clear this is the project-enumeration 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?

'Use this to choose a project' gives an explicit positive use case and a clear context for when the tool is appropriate. It doesn't name alternatives/exclusions, so it stops short of the top score, but the usage guidance is more than 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?

The description goes beyond the annotations by disclosing a non-obvious side effect: 'May renew and persist expired artifact download links.' This is important because despite the name 'list_tasks' implying a read-only operation, the operation is not guaranteed to be free of persistence effects. The annotation set already indicates readOnlyHint=false, and the description aligns with that 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?

Two short sentences deliver the core purpose, scope, pagination behavior, and a critical side effect without any filler. The most decision-relevant information 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?

Given the simple pagination parameters, the connection-scoped resource, the side-effect warning, and the presence of an output schema, the description is nearly complete. A slightly richer explanation of what qualifies as a 'durable export/report job' or when the renewal side effect occurs would make it fully self-sufficient, but nothing essential to invoking the 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 description coverage is 0%, but the description's mention of 'pagination' gives useful context for the limit and offset parameters. However, it does not explicitly define that limit caps the page size or that offset skips records, so the agent must rely mostly on the parameter names and schema constraints. This is adequate but not compensatory for the missing parameter descriptions.

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 ('List') and a concrete resource ('this connection's durable export/report jobs'), immediately distinguishing it from sibling list tools like list_comments or list_projects. The scope qualifier 'this connection's' makes the tool's target unambiguous despite the generic tool name.

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

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

The description clearly identifies when to use the tool: whenever the agent needs the durable export/report jobs associated with the current connection, with pagination supported. It does not explicitly name alternatives or exclusions, but the resource scoping is concrete enough to guide selection among the list_* 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 readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing an access requirement ('administrative access') and clarifying that credentials and login links are excluded from the output, which is behavioral information 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?

The description is two concise sentences, with the primary action front-loaded. Every phrase adds value: the verb and resource, the output scope, exclusions, and access requirement. There is no fluff or redundancy.

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

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

For a simple read-only listing tool with one optional parameter, an output schema, and annotations covering safety, the description is sufficient. It covers the key aspects: what is returned, what is excluded, and access requirements. Pagination or filtering details are not mentioned, but the output schema likely handles return format, so this is not a critical 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?

The schema covers the single optional parameter project_id with a full description, and the description adds no additional semantic meaning about the parameter. Since schema coverage is 100%, the baseline of 3 applies; the description does not compensate or extend parameter understanding.

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 clear verb and resource: 'List team members and project assignment'. It also specifies exclusions ('excluding credentials and login links'), which distinguishes it from other member-related operations like add_team_member or remove_team_member. The purpose is unambiguous and specific.

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

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

The description mentions a prerequisite ('Requires administrative access') but does not explicitly explain when to use this tool versus alternatives like list_projects or list_tasks. The usage context is implied by the resource name and verb, but no direct guidance is given about when to choose this tool over others.

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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, but the description adds meaningful behavioral context: the upload is private, the URL is expiring, and the service verifies ownership/type/size/completion before attaching. It also implies a two-step process (upload then attach), which is valuable beyond the annotations. Minor gap: it doesn't explicitly state that the upload URL is single-use or what happens on failure, but the provided context is strong.

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

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

The description is three sentences, each earning its place: what the tool returns, what the agent must do next, and what the service verifies. It is front-loaded with the core purpose and avoids redundancy with the schema.

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

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

The tool has an output schema (not shown in the prompt but indicated as present), and the description covers the workflow, verification behavior, and next steps. It doesn't explicitly mention error cases or rate limits, but for a preparation step with a clear follow-on action, it is nearly complete. The only notable omission is guidance on handling the expiring URL (e.g., time-to-live), but this is minor.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds context about the upload flow but doesn't add new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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's purpose: preparing a private upload for a reply attachment, returning a signed PUT URL and headers, and instructing the agent to upload bytes and pass upload_id to reply_to_comment. This distinguishes it from siblings like reply_to_comment and create_comment by focusing on the upload preparation step.

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

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

The description explicitly explains the workflow: call this tool to get the upload URL, upload the file bytes, then pass upload_id to reply_to_comment. It also notes that the service verifies ownership, type, size, and upload completion before attaching, which clarifies the expected sequence and prerequisites. This is strong guidance for when to use this tool versus 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 convey destructive and read-only hints, and the description adds meaningful context: the effect of revoking access, the administrative requirement, and the owner exclusion. It enriches the structured hints without contradicting them.

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 zero filler. The primary action and scope are front-loaded, followed by the prerequisite and the limitation. Every sentence earns its place.

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

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

For a one-parameter destructive tool, the description covers the required permissions, the scope of the action, the consequence (revoked access), and an edge case (owner cannot be removed). Combined with the output schema and fully documented parameter, nothing critical 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% and the only parameter, member_id, is already documented as 'Member ID to remove.' The description adds no further detail about the parameter, so the schema carries the full burden.

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

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

The description clearly states the action (remove), the resource (a team member), the scope (workspace and its projects), and an important exception (cannot remove the owner). This fully distinguishes it from sibling tools like add_team_member and assign_team_member.

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

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

The description gives clear context by stating the precondition of account-wide administrative access and the limitation that the owner cannot be removed. It does not explicitly name alternatives, but no sibling tool does the same removal operation, so the guidance is adequate.

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

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

Annotations already mark this as readOnly=false and destructive=true; the description adds meaningful behavioral constraints around Markdown support, attachment source restrictions, idempotent retries, and enforcement of connection write access. No statement contradicts the annotations.

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

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

Four sentences, front-loaded with the core purpose, with every sentence adding a practical constraint or workflow note. No filler or redundant restatement of the tool 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 write operation with annotations, output schema, and a high-coverage input schema, the description covers the remaining operational essentials: formatting, attachment prerequisites, retry behavior, and auth enforcement. No call-blocking information is missing.

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

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

Schema coverage is high (83%), but the description adds value by explaining Markdown Lite for text, requiring prepared upload references for attachments, and clarifying idempotency_key reuse for retries. These semantics supplement rather than repeat 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 uses a specific verb and resource ('Post a reply to feedback') and clearly indicates a write operation. It does not explicitly distinguish reply_to_comment from siblings like create_comment or update_comment, so it falls 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?

The description provides clear usage context: attachments must come from prepare_attachment_upload, URLs and local paths are rejected, and idempotency_key should be reused for retries. It names a prerequisite tool and gives exclusions, though it does not explicitly state when to prefer a sibling 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?

The annotations already declare the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds value beyond that by disclosing that results are limited to stable id, title, and citable URL, and that complete content requires a separate fetch call. This gives the agent an accurate model of the tool's partial-result 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?

Two sentences, no filler. The first sentence states the purpose and scope; the second provides return shape and the fetch hand-off. The most important information is front-loaded and every word earns its place.

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

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

For a single-parameter search tool with full schema coverage, a safety profile in annotations, and an output schema, the description covers everything an agent needs: what it searches, what it returns, and how to obtain full content. No critical gaps are apparent.

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

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

The schema already documents the single 'query' parameter with 100% coverage, so the baseline is 3. The description does not add any parameter-specific meaning (e.g., query syntax, supported filters) beyond what the schema provides, but it also doesn't need to given the complete 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?

The description states a specific verb ('Search') and resource ('authorized feedback') and clarifies that it returns sources with stable ids, titles, and citable URLs. The mention of using fetch for complete content distinguishes it from tools like search_comments and fetch, accurately framing its role as a pointer-returning search tool.

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

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

The description gives a clear usage context: use this tool to search across authorized feedback and obtain citable references, then follow up with fetch using the returned id for full content. It does not explicitly name alternatives or state when not to use it, but the routing instruction is strong enough for an agent to know the intended flow.

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, covering the safety profile. The description adds pagination behavior ('Results are paginated') and the default project scope, which are useful but not extensive. It does not mention rate limits, auth requirements, or output format, though output schema covers the latter.

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 sentences, front-loaded with the core purpose, and contains zero redundancy. It efficiently conveys the search scope, filter categories, default project behavior, and pagination without wasting words.

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?

Despite having 16 parameters, the schema and output schema carry most of the detailed information. The description covers the essential context: the default project scope when no filters are applied, and pagination. It does not explain how to combine filters or the return structure, but those are documented in the schemas, so the description is sufficiently complete for correct invocation.

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

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

Schema coverage is 81%, so most parameters have descriptions in the schema. The description lists filter dimensions (text, dates, author, status, tags, priority) that map to existing schema properties (query, created_after/before, author, status, tags, priority), but it adds no new semantic meaning beyond what the schema already provides. The baseline of 3 applies given high 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?

The description states a specific verb ('Search') and a clear resource ('authorized projects for website and asset feedback'), and lists the filter dimensions (text, dates, author, status, tags, priority). It effectively distinguishes from sibling tools like list_comments by emphasizing search across projects with filters, though it does not explicitly name an alternative tool.

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

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

The description provides a key usage condition: 'Without project filters, searches all projects granted to this connection.' This clarifies scope, but it does not explicitly state when to prefer this over alternatives like search or list_comments, nor does it mention any exclusions or complementary 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 annotations, the description reveals the async job model: tasks are durable, return an ID immediately, and require polling or cancellation. It also discloses client compatibility constraints. These are meaningful behavioral traits not captured by readOnlyHint, destructiveHint, or idempotentHint, and there is no contradiction with annotations.

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

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

The description is three short sentences with the core action and result front-loaded. Every sentence serves a purpose: what the tool does, how to follow up, and compatibility guidance.

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 async job-starting tool, the description covers the full workflow: start, poll, cancel, and client compatibility. The presence of an output schema and detailed nested argument schema means return shape and parameter details are already available, so nothing essential for correct invocation 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?

Top-level schema description coverage is only 33%; operation and arguments lack descriptions, and the tool description does not explain the operation enum or how to structure the arguments object. The nested argument properties are documented in the schema, but the description itself adds almost no parameter-level guidance to compensate for the low 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?

The description clearly states the action (start), the resource (a durable export or report job), and the immediate result (return its ID). It also distinguishes this from lifecycle tools like get_task and cancel_task by positioning start_task as the creation step. No vague phrasing or tautology.

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

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

The description gives concrete lifecycle guidance: poll get_task at the returned interval, or use cancel_task, and notes compatibility with clients lacking the experimental MCP tasks extension. It does not explicitly contrast start_task with synchronous export/report siblings, but the intended usage context is clear.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true. The description adds genuinely useful behavioral context beyond that: changing visibility can expose feedback to clients, and setting archived=false restores rather than deletes. These warnings help the agent anticipate side effects not encoded in 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?

Two sentences with zero redundancy. The main action is front-loaded, and the two most consequential side effects (visibility exposure, restore behavior) are stated efficiently. Every clause earns its place.

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

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

For a 9-parameter mutating tool with an output schema, this is fairly complete: it covers the primary behavior, the main risk, and the archive restore nuance. Idempotency and project context are already covered by the schema and annotations, so nothing critical is missing for correct invocation.

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

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

Schema description coverage is 78%, so the schema already documents most parameters. The description adds the word 'replacement' for tags, which aligns with the schema's 'complete replacement list,' and hints at visibility semantics. This is marginal added value beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific action ('Set') and enumerates the target fields (status, priority, tags, visibility, archive state), which clearly distinguishes it from the narrower sibling update_comment_status. However, it never explicitly names the resource as a comment, relying on the tool name and schema for that.

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

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

The description provides no when-to-use guidance or alternatives. Even though a specialized sibling update_comment_status exists, the description never tells the agent when to prefer this generic update over the specialized one, forcing the agent to infer the decision from field names.

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

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

Annotations already declare the tool is a write operation (readOnlyHint=false), idempotent, and potentially destructive. The description adds the important behavioral constraint that statuses must come from get_project_context for the selected project, which is non-obvious and beyond what the annotations state. No contradiction with annotations.

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

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

Two short sentences carry the essential action and the key prerequisite without any filler. The main verb and resource are front-loaded, and every word 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 a rich input schema, annotations, and an output schema present, the description covers the main action and prerequisite adequately. It does not mention when to use the single-comment tool versus bulk_update_comments, but the name and description make the primary use case clear enough.

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 83%, so the input schema already documents most parameters well. The description's guidance about valid statuses repeats what the status parameter description already says ('Call get_project_context to obtain current choices'), so it adds little beyond the schema. Priority is self-explanatory via its enum.

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 ('Set') with a precise resource ('a comment's status and/or priority'), which clearly distinguishes this from sibling tools like update_comment or create_comment. The scope is unambiguous and an agent can tell exactly what operation this performs.

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

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

The description gives a clear prerequisite: 'Obtain valid statuses from get_project_context for the selected project,' telling the agent that statuses are project-specific and must be fetched first. It does not explicitly name alternatives or exclusions (e.g., when to use bulk_update_comments), 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 indicate destructiveHint=true and idempotentHint=true. The description adds valuable context: it requires settings permission, and warns that access-setting changes can affect who sees feedback. It also clarifies partial updates ('explicitly specified settings'), which is useful behavioral information beyond 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?

Three sentences, each earning its place: what it does, the permission requirement, and a caution about access-setting side effects. No redundancy or filler.

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

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

The tool has a rich schema and output schema, so the description doesn't need to explain return values. It covers the key behavioral aspects: permission requirement, partial update semantics, and the side-effect warning. It could mention idempotency or reversibility, but annotations already cover idempotency and the description's warning is sufficient 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 description coverage is 50%, and the description doesn't add parameter-level detail beyond what the schema provides. The nested 'settings' object is well-documented in the schema, so the description doesn't need to compensate much. The description's mention of 'explicitly specified settings' clarifies the partial-update semantics of the settings object, which adds some value.

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 ('Change') and resource ('project settings'), and clarifies that only explicitly specified settings are changed. It distinguishes itself from get_project_settings by implying a write operation, though it doesn't name the sibling explicitly.

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

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

The description provides clear context: requires settings permission, and advises inspecting current settings first. It doesn't explicitly name alternatives or when-not-to-use, but the guidance is sufficient for an agent to know when to invoke it.

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