Comma

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

With no annotations, the description carries the full behavioral burden, and it discloses little beyond the name: that a comment is created and that it can be anchored. It says nothing about permissions, whether the comment is public immediately, whether it triggers a notification (a create_notification sibling exists), or whether the operation is idempotent. Anchoring behavior (must the excerpt exist in the report?) is also 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 short sentences, zero filler, with the core action front-loaded and the optional anchoring clause second. Nothing needs trimming.

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

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

For a 6-parameter mutation tool with no annotations and no output schema, the description is minimal but covers the essential action and the anchoring option. It omits failure conditions, permissions, and notification side effects that would help an agent 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 every parameter is already documented in the schema, giving a baseline of 3. The description adds only the relational idea that anchoring is optional and is done via 'a text excerpt or block id,' which does not cover anchor_prefix/anchor_suffix or add syntax 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?

The description gives a specific verb and resource ('Create a top-level comment on a report') and the word 'top-level' implicitly distinguishes it from the sibling reply_to_comment. It stops short of explicitly naming alternatives, but an agent can tell what resource is being written.

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

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

Usage is only implied: 'top-level' hints that threaded replies belong to reply_to_comment, and the optional anchoring is described. There is no explicit when-to-use statement, no prerequisites (e.g., whether the report must be shared or the caller must be a reviewer), and no exclusions.

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

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

With no annotations, the description carries the full burden and does it well: it discloses the verification step against the provider, encrypted storage, that the token is never returned, and that re-connecting rotates the stored token. It omits failure behavior for invalid tokens and any permission requirements, which keeps it short of a 5.

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

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

Three short sentences, zero filler, with the primary action and outcome front-loaded and the token-handling caveats following. 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?

No output schema exists, and the description covers the key security and mutation semantics an agent needs (encrypted storage, no token return, rotation on re-connect). It does not describe what a successful response contains or error handling for a bad token, leaving a minor gap.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying that the token is provider-verified and encrypted, and that re-connecting the same provider rotates the stored credential — which tells the agent provider identifies the connection slot.

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

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

Specific verb (connect) plus resource (integration) plus the two supported providers, and it states the downstream benefit (posting report links to PRs/issues). It is clearly distinct from disconnect_integration and list_integrations in the sibling set.

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 when this is needed (to let Comma post report links) and notes that re-connecting rotates the token, which is useful usage context. However, it never states prerequisites, who is authorized, or routes the agent to alternatives such as list_integrations to check existing connections.

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 no annotations present, the description carries the full burden and does well: it discloses that the secret is encrypted at rest and never returned, that config/secret are schema-validated per kind, and that (kind,label) must be unique per account. It omits auth/permission requirements and error behavior, so it is strong but not exhaustive.

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

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

Two dense sentences, front-loaded with the core definition and followed by constraints. Every clause carries distinct operational information (catalog source, validation, encryption, uniqueness) 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 mutation tool with no annotations and no output schema, the definition covers creation semantics, validation inputs, and the sensitive-data behavior ('never returned'). It stops short of stating permission requirements, failure modes, or what a successful create returns, which leaves a modest gap.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds semantics the schema lacks: the catalog source and validation rules for `kind`, per-kind schema validation for `config`/`secret`, and the cross-field uniqueness constraint on (kind,label). That is genuinely additive constraint information rather than restatement.

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+resource and goes further by defining what a connector is ('an encrypted credential a skill can use'), which lets an agent distinguish it from unrelated create_* siblings like create_report or create_skill. It is clear but does not explicitly contrast with any adjacent tool beyond pointing at list_connectors.

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 concrete prerequisite: `kind` must come from the catalog kinds exposed by list_connectors, and config/secret are validated against that kind's schema, which effectively routes the agent through list_connectors first. There is no when-not guidance, but there is no true alternative to this tool among the 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?

With no annotations, the description carries the full burden. It usefully discloses scope semantics ('every report you own, were invited to, or share with your team (public link access doesn't count)') and defaults, but says nothing about authentication needs, whether deliveries are verified, rate limits, or failure 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?

Three tight sentences with the core purpose front-loaded, followed by scoping and defaults. The defaults sentence partially duplicates schema fields but still reads efficiently 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 6-parameter create tool with no annotations and no output schema, the description covers purpose, scoping, and defaults adequately but omits prerequisites, whether a notification identifier is returned for later use, and any note on delivery/verification behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the events and format defaults already documented in the schema and adds only the 'public link access doesn't count' nuance for report_id, while saying nothing about name or signing_secret (both already covered by 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 opening sentence states a specific verb and resource ('Subscribe a webhook to report events'), which clearly separates it from list_notifications and delete_notification. It does not, however, differentiate from the potentially similar create_connector sibling, 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 report_id omission rule and the events/format defaults give clear operational context, but this is parameter-usage guidance rather than tool-selection guidance. There is no statement of when to use this instead of connect_integration or create_connector, nor any exclusions.

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

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

With no annotations, the description carries the burden and does so well: it discloses that share links are not search-indexed, that commenting requires a free sign-in, that relative asset refs are rewritten to public URLs in one call, that re-uploading a relative_path replaces it, and that source_recipe.prompt is visible to every viewer. It omits auth/scope requirements and rate limits, so not a 5.

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

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

The description is dense but front-loaded: the core action and the key default come first, followed by overrides, asset behavior, and the return shape. It is somewhat long for a schema that already documents every parameter, so a small amount of overlap with the schema keeps it from a 5.

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

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

For a 10-parameter, nested-object tool with no output schema, the description covers the essentials: required vs optional intent, default and enum behavior, the asset-rewriting workflow, and the returned fields (report id, visibility, public_permission, edit_url, share_url). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the effect of visibility and public_permission on actual viewer behavior, the purpose of producer_name (public attribution watermark), and the warning that source_recipe.prompt is shown to all viewers and should only be passed on request.

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

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

The description opens with a specific verb+resource+outcome: 'Upload a new HTML report to Comma and get back an absolute share_url.' It implicitly separates itself from siblings by noting that assets can be passed in the same call 'instead of creating the report, uploading, and patching the HTML yourself,' distinguishing it from upload_report_asset and create_report_from_url.

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

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

States defaults (visibility='public', public_permission='comment') and the exact overrides to use for owner-only or read-only links, and explicitly routes team/domain audiences to the sibling set_report_sharing ('create then call set_report_sharing'). It also conditions source_recipe.prompt on 'only pass it when the user asks.' No explicit exclusion of create_report_from_url by name, so not a full 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?

With no annotations, the description carries the full burden and discharges it well: it discloses asset inlining into a self-contained HTML doc, headless-browser rendering of SPAs/app-builder pages, page-reachability preconditions, and the bot-protection failure mode. It also states the return artifacts (id, /r/:id edit URL, /p/:id share URL), which is information no structured field supplies since there is no output 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?

Purpose and the key rendering behavior are front-loaded, and each sentence contributes distinct information (mechanism, return values, triggers, constraints). The long em-dash clause describing the headless-rendering path is dense but justified; there is little wasted text.

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

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

No output schema exists, so the description correctly explains the return shape (id plus edit and share URLs). Combined with the reachability constraints and rendering behavior, an agent has everything needed to decide to call it and to predict the outcome.

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 url, title, visibility and public_permission are already documented in the schema, including enums and defaults. The description adds no syntax, format or edge-case guidance beyond the schema's own text, 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 opens with a specific verb and resource ('Import a public web page into Comma as a report') and immediately establishes the scope that separates it from create_report: source content comes from a fetched URL. An agent can distinguish this from the manual report-creation sibling 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 names concrete trigger phrasing ('import this page/site/dashboard/app into Comma', 'turn this URL into a Comma doc') and states the exclusion conditions clearly (must be publicly reachable, no login, bot-protected pages fail). It does not name create_report explicitly as the alternative for non-URL report creation, 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?

With no annotations, the description carries the full burden and largely succeeds: it discloses the webhook behavior (Comma POSTs report content to reviewer_url, reviewer replies with comments) and the auto_on_revision default. It omits failure/error behavior and confirmation of auth-header encryption (that lives in schema), but the core runtime behavior is disclosed.

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

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

Three tight sentences, front-loaded with the purpose and followed by the two most consequential behaviors. No filler, though the report_id/auto_on_revision sentences overlap with schema text.

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

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

For a no-annotation, no-output-schema creation tool, the definition covers purpose, scoping, and automatic-run behavior. It leaves out response shape and failure modes, but those are minor given the otherwise complete coverage of the call decision.

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 7 parameters in detail. The description largely restates the report_id scoping and auto_on_revision default rather than adding new syntax or semantics, 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?

States a specific verb and resource ('Register an agent-reviewer') and immediately distinguishes it from siblings like list_reviewers/update_reviewer/delete_reviewer by describing the creation semantics. An agent can tell what this tool produces without opening the schema.

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

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

Gives explicit conditional guidance for the key decision: set report_id to scope to one report versus omit it for an org-wide reviewer. It does not explicitly name sibling alternatives for updating/deleting, but the when-to-use context 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?

With no annotations, the description carries the full burden and does notable work: it discloses the execution model (POSTs to webhook vs. runs a skill each tick), the cron cadence, the absence of a per-plan routine cap, and the billing implication (prepaid credits, or free on your own Bedrock key). It does not cover required permissions or what the creation returns, which are the remaining gaps.

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

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

Front-loaded with the core action before details, and the trigger/skill, cron, cap, and billing clauses each add distinct information. It is dense as a single paragraph, but no sentence is 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 9-parameter mutation tool with no annotations and no output schema, the description covers the important behavioral context (execution target, cadence, cost, param relationship). What an agent still lacks is permission requirements and the post-creation result, leaving a modest gap.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents each parameter including cron format. The description adds real value beyond it by stating the mutual exclusivity of `trigger_url` and `skill_id`, a constraint not expressed in the schema itself.

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 ('Create a routine that re-runs on a cron schedule against a report'), and goes further to define what a routine is (cron-triggered, report-maintaining) rather than merely restating the name. An agent can distinguish it from create_report, create_skill, or create_connector 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?

Gives a concrete operational rule: provide either `trigger_url` or `skill_id`, with the consequence of each spelled out. It stops short of naming alternatives or exclusions (e.g. when to use update_routine instead), but the context is clear enough to invoke correctly.

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 no annotations, the description carries the full burden and does disclose real behavior: skill_md's YAML frontmatter is parsed for name/description/prompt/required tools/model, and other params override parsed values, plus the schedule-run consequence. It stops short of permissions, validation limits, or what the call returns, but it is well above a bare imperative.

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 core action, then the two modes, then the fallback endpoint. No filler; each clause carries information an agent needs to choose a calling pattern.

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 6-param create tool with no output schema and no annotations, it covers the creation modes, parameter interlock, downstream lifecycle, and out-of-scope cases. It omits any indication of the return value (e.g., a skill id) and permission/auth requirements, leaving a small gap.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds mode-level meaning beyond the individual field docs: it pairs name+prompt as one mode, skill_md as the other, and explains the frontmatter-parsing/override relationship between them. That relational context is useful even though per-field requiredness is already in the schema.

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

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

States a specific verb+resource ('Create a skill') and immediately distinguishes its two creation modes (author with name+prompt vs upload skill_md). An agent can tell exactly what this does and how it differs from siblings like list_skills or delete_skill.

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

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

Explicitly names the two invocation paths and their required params, gives the downstream use case (attach to a routine via create_routine's skill_id), and routes the agent elsewhere for zip/GitHub skills (REST POST /api/v1/skills). This is a genuine when/when-not with an alternative.

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?

No annotations are supplied, so the description carries the full behavioral burden. It usefully discloses the external_url branch (embedding, page-level comments, no build), but this largely duplicates the external_url schema text and it says nothing about permissions, return value, or what happens to the created site.

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 core action and then the branching logic; every sentence contributes. It is slightly dense with parentheticals, but there is 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 4-parameter creation tool with no annotations and no output schema, the description covers the key create-vs-link decision well but omits the creation result and any permission/auth expectations, leaving a real gap given the absence of annotations and an output schema.

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

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

Schema coverage is 75%, so the schema already documents name, framework, and external_url behavior. The description restates the framework enum/default and external_url semantics rather than adding format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a new website') and immediately resolves the ambiguity by naming the two modes: a deploy target vs. a linked external site. It also names the sibling deploy_website, so an agent can distinguish this tool from the other website/creation tools without opening the schema.

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

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

Gives clear routing: 'then call deploy_website to push source' for deploy targets, and 'pass external_url to link an EXISTING live site... no deploy' for the other branch. The condition selecting each path is explicit, though it frames deploy_website as a follow-up rather than stating a when-not condition.

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 no annotations, the description carries full behavioral burden. It usefully discloses an ownership restriction and one side effect ('Routines referencing it keep their other connectors'), which are non-obvious traits. However, it omits irreversibility, confirmation behavior, and what happens to the connector's data — significant gaps for a destructive operation.

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

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

Two short sentences, zero filler, with the core action front-loaded and the non-obvious side effect placed second. 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 single-parameter delete with full schema coverage and no output schema, the description covers the essentials: what it does, the ownership gate, and the effect on dependent routines. Only the destructive/irreversible nature is left unstated, which is a modest gap.

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

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

Schema description coverage is 100% — the single connector_id parameter is fully documented as a UUID in the schema — so the baseline of 3 applies. The description adds nothing about the identifier beyond reaffirming that the target must be one the caller owns.

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+resource ('Delete a connector') and adds a scope qualifier ('you own'), which is more informative than the bare name. It does not, however, differentiate itself from the many other delete_* siblings (delete_routine, delete_skill, etc.) beyond the resource noun itself.

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 implies the precondition for use ('a connector you own'), which is useful, but gives no explicit when-to-use guidance, no alternative tools (e.g., disconnect_integration), and no note about when deletion is inappropriate. Usage is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond the operation itself. It does not state that deletion is irreversible, what happens if the id does not exist, whether it fails silently, or what permissions are required — key omissions for a destructive operation.

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

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

A single front-loaded sentence with zero filler; the operation and selector come first. Nothing is wasted, though there is also very little 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?

For a destructive one-parameter tool with no annotations and no output schema, the description is too thin: irreversibility, failure behavior on unknown ids, and auth expectations are all unstated. The rich schema on the single parameter partly compensates, but the mutating semantics are not 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 specifies the parameter as a "UUID from list_notifications," so the baseline is 3. The description's "by id" adds nothing beyond what the schema field already documents.

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

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

The description gives a specific verb ("Remove") and resource ("notification subscription") and indicates the selector ("by id"), so the agent knows exactly what operation it performs. It does not explicitly name its siblings (create_notification, list_notifications), so differentiation is inferable rather than stated.

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

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

There is no guidance on when to use this versus alternatives such as create_notification or list_notifications, nor any prerequisite or precondition (e.g. needing the subscription to exist). The agent must infer usage entirely from the tool name.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that both the storage object and the database row are removed, and that the report HTML is left untouched, causing referencing <img src> tags to 404. It does not state permission requirements, error behavior for a missing id, or whether deletion is reversible.

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 action and its mechanical effect, then the user-visible consequence. Every sentence earns its place 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 destructive tool with no annotations and no output schema, the description covers what gets removed and the downstream effect on reports. Missing only secondary details like permission prerequisites and behavior on an unknown asset_id.

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

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

Schema description coverage is 100%, so both required params (asset_id, report_id) are already documented, including the pointer to list_report_assets as the source of asset_id. The description's 'by its id' adds nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb (delete) and resource (previously-uploaded asset) and scopes it to deletion by id. It is clearly distinguishable from sibling delete_connector/delete_routine/delete_skill and from upload_report_asset, its inverse.

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

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

The use case is implied by the verb and the schema cross-reference to list_report_assets, but there is no explicit when-to-use guidance, no note about irreversibility, and no statement of what to do instead (e.g., re-upload via upload_report_asset). Adequate but with a clear gap.

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 no annotations, the description carries the full burden and does disclose two important behaviors: the ownership requirement and the cascade effect on existing comments (reviewer_id set to null). It omits irreversibility confirmation and failure behavior for a non-owned or invalid reviewer_id, so it's strong but not complete.

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 tightly written sentences with zero filler; the destructive action and its data side effect are both front-loaded.

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

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

For a single-parameter delete with no output schema and no annotations, the description covers the key side effect and ownership gate. Missing a note on whether deletion is permanent/confirmed, but nothing critical is left for the agent to guess about the core operation.

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

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

Schema description coverage is 100%, so the single reviewer_id parameter is already documented as a UUID. The description adds only the implicit constraint that the reviewer must be caller-owned, which is context rather than parameter syntax; baseline 3 applies.

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

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

States a specific verb+resource ("Delete an agent-reviewer") and adds the ownership qualifier, which distinguishes it from create_reviewer/update_reviewer/list_reviewers. An agent can identify the operation without opening the schema.

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

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

The "you own" phrasing implies the precondition, but there's no explicit when-to-use vs. alternatives guidance (e.g., update_reviewer for modification, list_reviewers for lookup) and no when-not-to-use or irreversibility warning. Usage is implied rather than stated.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses two key traits: the caller must own the routine, and deleting it also removes its run history. It does not state whether the deletion is irreversible or what happens if ownership fails, but it adds meaningful context beyond the bare tool name.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the action, ownership condition, and cascade effect efficiently.

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

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

For a simple one-parameter delete tool with full schema coverage and no output schema, the description covers the essential scope: what is deleted and that run history is included. It could mention irreversibility, but it is otherwise complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the single routine_id parameter is already documented in the schema. The description does not add any format, constraint, or usage detail beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description gives a specific verb and resource: delete a routine. It also states the ownership constraint and the cascade to run history, which clearly distinguishes it from sibling tools like update_routine, run_routine, or list_routines.

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 when deletion is appropriate but provides no explicit when-to-use or when-not-to-use guidance. It does not name alternatives such as update_routine or list_routines, and it gives no prerequisites beyond the implied ownership condition.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose one genuinely non-obvious side effect — referencing routines keep working but their skill_id becomes null — and an ownership requirement. It omits irreversibility, permission-failure behavior, and whether referenced routines can block deletion, so the disclosure is partial.

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

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

Two short sentences, zero filler, and the core action and the key side effect are both front-loaded. 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 single-parameter, no-output-schema delete tool, the description covers purpose, ownership, and the main referential side effect adequately. A brief note on irreversibility or permission errors would make it fully 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?

There is only one parameter and schema description coverage is 100% ('UUID of the skill'), so the schema already does the semantic work. The description only adds the ownership constraint on the target skill, which is a marginal addition. 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 ('Delete a skill') plus an ownership scope ('you own'), which no sibling (list_skills, create_skill) shares. An agent can tell exactly what this does without opening the schema.

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

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

The ownership qualifier ('a skill you own') implies a precondition for use, which is useful context. However, it names no alternatives, no when-not-to-use conditions, and no note that deleting is likely irreversible. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the provider builds and hosts the site, the TTL-based takedown and redeploy requirement, and hard limits (max 2000 files / 25 MB, UTF-8 text). It does not mention auth/permissions, but the operational constraints are unusually well covered.

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

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

Four tight sentences, front-loaded with the action, then the input format, then runtime behavior and lifecycle. Nothing is redundant and each sentence adds callable 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 two-param, no-output-schema tool with no annotations, the description covers input format, limits, hosting behavior, lifecycle, and where to fetch the resulting URL. Only the permission model is unaddressed, which is a minor gap given the otherwise thorough 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 the baseline is 3, but the description adds value beyond the schema by specifying the exact files:[{path, content}] shape, UTF-8 encoding, and the 2000-file / 25 MB limits that the schema does not include. It reinforces rather than merely restates the parameter docs.

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 ('Deploy source files to a website') and implicitly contrasts with siblings by pointing to read_website for the live URL and by dealing with an existing website_id rather than create_website. An agent can distinguish this from create_website/list_websites 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?

Gives useful follow-up guidance ('poll read_website for the live URL') and lifecycle context ('redeploy to bring one back'), but never states when to choose this over alternative siblings or any prerequisites beyond the mechanics. Usage is implied rather than explicit.

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

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

With no annotations provided, the description carries the full behavioral burden but supplies almost nothing: it doesn't disclose whether the removal is reversible, whether stored credentials/tokens are revoked, whether it requires elevated permissions, or what dependent resources are affected. For a destructive mutation tool this is a significant 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?

A single tight sentence with the core action front-loaded and no wasted words. It is arguably under-specified rather than concise, but structurally clean and appropriately sized for a one-param tool.

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 is structurally simple (one required id, no output schema, no nested objects), so not much explanation is strictly required. But with no annotations and no description of side effects or reversibility after removal, an agent lacks enough to invoke it confidently in a destructive scenario.

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

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

Schema coverage is 100%, so the schema already documents integration_id including its provenance ('UUID from list_integrations'). The description's 'by id' adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('remove') and resource ('connected integration'), clearly distinguishing it from siblings like connect_integration and list_integrations. However, it doesn't clarify whether 'remove' means deleting the integration config entirely or merely severing the connection while retaining it, which matters given the tool name says 'disconnect'.

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

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

No explicit guidance on when to use this versus connect_integration, list_integrations, or delete_* siblings, and no stated prerequisites. The only routing hint is the schema's mention of 'UUID from list_integrations', which is not in the description itself.

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 no annotations, the description carries the full behavioral burden, and it does disclose two meaningful traits: the return content (metadata plus stored HTML) and the authorization requirement (view permission). Missing are failure behavior for a nonexistent id and whether the HTML is rendered or raw, 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 action and payload. Every clause carries information; nothing is 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 correctly steps in to say what is returned (metadata + stored HTML) and notes the permission requirement. It stops short of covering not-found behavior and how it differs from read_report, so it is strong but not 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?

Only one parameter, already fully documented by the schema ('Report id (UUID)'). The description's 'by id' restates the schema without adding format, lookup, or edge-case semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a report by id') and adds the distinguishing payload ('metadata + the stored HTML'). It is clearly differentiated in substance from list_reports, but it never names a sibling such as read_report, which may well overlap with fetching a report — that ambiguity keeps it at 4.

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

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

Usage is only implied by 'by id' — the agent can infer this is the lookup-by-identifier path, and 'Requires view permission' gives a prerequisite. There is no explicit when-to-use versus list_reports/search_reports/read_report, and no when-not guidance.

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

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

With no annotations and no output schema, the description carries the full burden and does so well: it enumerates the returned fields (reviewer, optional note, is_stale) and explains the critical semantic that is_stale=true invalidates an approval for current content. This is exactly the behavioral context an agent needs before acting on a verdict.

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

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

Three tight sentences, correctly front-loaded: purpose first, field contents second, decision-relevant warning last. 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 single-parameter read tool with no output schema, the description covers purpose, return fields, and the staleness caveat. It could have explicitly stated the operation is read-only, but otherwise nothing essential is missing.

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

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

Schema description coverage is 100% for the single report_id parameter, so the schema already documents it fully. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (review verdicts on a report) and even names the possible verdict values (approved / changes_requested). This clearly distinguishes it from get_report, read_report, and the write-side set_report_signoff.

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 an explicit use condition: 'Check this before promoting or distributing a report.' That tells the agent when the tool matters, though it does not name sibling alternatives or state exclusions.

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

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

With no annotations, the description carries the full burden and does disclose real behavior: cursor pagination via nextCursor, a per-comment cap of 50 embedded replies, and a replies_truncated flag with a REST endpoint to retrieve the rest. It omits ordering, permissions, and the read-only nature (implied only by 'List').

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

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

Three tight sentences with zero filler; the core purpose leads, followed by the pagination contract and the truncation edge case. Every sentence carries operational value.

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

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

With no output schema, the description usefully explains the two return-shape elements an agent must act on (nextCursor and replies_truncated). Other comment fields and result ordering remain unspecified, a minor gap for a read-only listing tool.

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

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

Schema coverage is 100%, so limit, cursor, and report_id are already documented in the schema. The description only restates cursor usage ('pass the returned nextCursor'), adding no syntax, format, or default detail beyond what is structured.

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 comments + replies') plus the scope ('on a report'), which separates it from the sibling list_website_comments. An agent can tell immediately which collection is returned.

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

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

Usage is implied rather than stated: the pagination mechanics tell the agent how to iterate, and the REST fallback hints at when the embedded replies are insufficient, but there is no explicit when-to-use guidance or mention of reply_to_comment / set_comment_status as related 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?

With no annotations, the description carries the full burden and does disclose the most important behavioral fact: 'Secrets are never returned.' It also describes the payload (connectors plus kind catalog and config/secret schemas), removing ambiguity about what a read of this tool exposes. It does not mention pagination, permissions, or that the operation is non-mutating beyond what 'list' 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 front-loaded sentences that state the primary action first and the secondary payload second, with the security caveat last. The parenthetical vendor list is longer than strictly necessary but earns its place by defining what a 'connector' is for an unfamiliar agent.

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

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

For a zero-parameter, no-annotation, no-output-schema tool, the description does the work structured data cannot: it explains what comes back (connectors + kind catalog + config/secret schemas) and the redaction guarantee. The only gap is the absence of any tie-breaker against the sibling list_integrations.

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

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

The tool takes zero parameters, so the baseline is 4; there is no argument syntax for the description to clarify. The description correctly implies no filtering arguments are needed.

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

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

States a clear verb+resource ('List your connectors') and adds substantive scope detail: it returns both the user's connectors and the catalog of connector kinds with their config/secret schemas. It does not explicitly distinguish itself from the sibling list_integrations, so an agent must infer that connectors (credentials) differ from integrations.

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

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

Usage is implied by the content (you'd call this to see existing connectors and the available kinds before or after create_connector/delete_connector), but there is no explicit when-to-use, when-not-to-use, or named alternative. No prerequisite or ordering guidance is given.

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

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

With no annotations, the description carries the full burden and does deliver a genuine behavioral trait: access tokens are never returned, which is a security-relevant guarantee an agent could not infer from the empty schema. It still omits auth requirements and pagination behavior, so not a 5.

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

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

Two short sentences, front-loaded with the action and immediately followed by the most important behavioral caveat. Every clause earns its place 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 zero-param list tool with no output schema, the description usefully names the returned fields (provider, account label, status), compensating for the missing schema. It stops short of noting ordering or empty-state behavior, but nothing critical to correct invocation is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. The description correctly implies the call is a simple unfiltered listing scoped to the caller's own account.

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 (List) and resource (connected GitHub / Linear integrations) in the first clause. An agent can immediately distinguish it from connect_integration and disconnect_integration among the sibling tools.

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

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

The phrase 'your connected' implies the tool surfaces existing integrations rather than creating them, which is a usable hint. However, no explicit when-to-use versus connect_integration/disconnect_integration guidance or prerequisites are given, so usage is only implied.

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

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

With no annotations, the description carries the full load and does add real context: it enumerates the events delivered (revision.created, comment.created, comment.mentioned, signoff.submitted) and the webhook formats (Slack, Discord, plain JSON). However, it does not state that this is a read-only operation, whether results are paginated or truncated, or the format of the returned list — gaps a zero-annotation read tool should close.

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 purpose front-loaded and the explanatory detail second. No filler, no repetition of the tool name's meaning.

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

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

For a zero-parameter list tool with no output schema, the description provides enough to understand what will be listed and what those subscriptions do. It stops short of describing the returned fields or ordering, which leaves a small but real 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 tool takes no parameters, so the baseline is 4; there is nothing for the description to disambiguate. No misleading parameter information is present either.

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

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

Names a specific verb and resource ('List your notification subscriptions') and goes further by explaining what a notification subscription actually is. It is distinguishable from list_* siblings (list_reports, list_routines) by resource, though it never explicitly contrasts with create_notification or delete_notification.

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

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

There is no statement of when to use this versus the sibling mutators (create_notification, delete_notification) or any prerequisite/context for invoking it. Usage is only inferable from the tool name, so the description contributes no 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?

No annotations are provided, so the description carries the full behavioral burden. It does not state whether the operation is read-only, what permissions are required, whether results are paginated, how the public URLs behave, or what happens with reports that have no assets.

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 compact sentences, no filler. The core purpose is front-loaded, followed by the usage motivation.

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?

It covers purpose and usage intent, but for a tool with no annotations and no output schema, the description omits safety profile, auth requirements, pagination, and return shape. Adequate but with clear gaps given the absence of structured behavioral data.

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 report_id parameter is fully documented in the schema, so the description adds no parameter-level detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (assets attached to a report), and adds the return content (public URLs). It is clearly distinguishable from siblings like get_report, list_reports, and upload_report_asset.

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

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

Gives a clear use context: discovering what's already uploaded before adding more or referencing existing files. This implicitly routes the agent away from upload_report_asset, though it doesn't name the alternative explicitly or state exclusions.

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

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

With no annotations, the description carries the full burden and does well: it discloses the ownership scoping, sort order, and the returned field set, and explicitly warns that the HTML body is not included. It stops short of describing pagination behavior or the auth requirement beyond 'authenticated user'.

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 scope and ordering, then the return shape, then the alternative. No filler and every clause carries 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?

There is no output schema and no annotations, so the description's return-field summary is genuinely load-bearing and covers the essentials for a zero-required-param list tool. It could say more about empty results or how cursors behave across concurrent updates, but 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%, so limit and cursor are already fully documented in the schema. The description adds no syntax, default, or cap detail beyond what the structured fields provide, so the baseline of 3 applies.

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

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

States a precise verb+resource ('List reports'), adds the scope ('the authenticated user owns') and the ordering ('most-recently-updated first'), which cleanly separates it from search_reports and list_report_assets. An agent can identify the operation without opening the schema.

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

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

Explicitly routes to get_report for fetching a report body and implies the read-only listing context, but it never distinguishes this from the closest sibling, search_reports, which an agent could easily confuse with a plain list. Clear context, incomplete alternative coverage.

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 no annotations, the description carries the full burden, and it does add real domain context: a reviewer is a webhook that receives report content and posts back comments, and reviewers with report_id=null apply to all owned reports. However, it says nothing about return shape, ordering, or pagination for a list operation with no output 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?

Front-loaded with the core action, then two tight sentences that define the reviewer concept and the report_id=null rule. Efficient overall, though the mid-sentence 'Comma calls with a report's content' phrasing reads as a garbled artifact.

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

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

For a zero-parameter list tool with no annotations and no output schema, the description gives the essential conceptual framing of what a reviewer is and how report_id scoping works. It still leaves the agent without any sense of what the response contains or how results are ordered, which matters when no 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?

The tool takes zero parameters, so the baseline is 4. The description's mention of reviewer_url and report_id refers to the entity's fields, not call arguments, so there is no parameter detail to add or omit.

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 the agent-reviewers you own') with clear ownership scope, which separates it from create_reviewer/update_reviewer/delete_reviewer by verb alone. It stops short of explicitly naming those siblings, so it does not reach a 5.

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

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

Usage is only implied — the agent can infer this is the read path for reviewers owned by the caller, and the report_id=null note hints at scoping semantics. There is no explicit when-to-use statement or pointer to alternatives such as create_reviewer or get_report_signoffs.

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 no annotations, the description carries the full behavioral burden. It usefully explains what a routine *is* (cron-scheduled, webhook via trigger_url or skill_id, can republish a report), but says nothing about the operation itself — ordering, pagination, whether shared/other-owned routines appear, or permission requirements.

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

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

Two tight sentences with the core action front-loaded and zero filler. The second sentence is domain education rather than operational detail, which is defensible but slightly dilutes focus.

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 no-param list tool with no annotations and no output schema, the description covers the resource but not the result — there is no hint of what fields come back or how many, which the absence of an output schema would otherwise warrant.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. No parameter-level meaning is missing or misstated.

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

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

Specific verb ('List') plus resource ('routines') with a clear ownership scope ('you own'), which separates it from listing other users' routines. It does not, however, name or contrast with adjacent siblings like get/run/update_routine, so differentiation is left to the name alone.

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

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

Usage is only implied: an agent can infer this is the read path for routines, but there is no explicit when-to-use statement, no mention of prerequisites, and no routing to alternatives such as run_routine or list_skills.

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 no annotations, the description must carry the behavioral load. It discloses the ownership scoping and enumerates the return fields (prompt, required tools, source, model), which is genuinely helpful. It says nothing about pagination, ordering, rate limits, or auth requirements, but for a zero-parameter read-only list the risk surface is small.

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, front-loaded with the action and scoped by 'you own', with the second sentence efficiently supplying the domain definition and the payload shape. No waste.

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

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

For a no-argument list tool with no output schema, the description compensates well by naming the fields returned (prompt, required tools, source, model). Only minor details like ordering or result volume are absent, which is acceptable at this complexity.

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

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

The tool takes no parameters (schema coverage 100% trivially), so per the baseline a 4 is appropriate; there is no parameter semantics to add meaning to.

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 the skills you own') and even defines what a skill is, so an agent unfamiliar with the domain understands the entity. It doesn't explicitly name or differentiate from the sibling create_skill/delete_skill tools, but the list verb plus the ownership scope makes the distinction 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 phrase 'you own' implies the context (retrieving only the caller's own skills), which is useful scoping guidance, but there is no explicit when-to-use statement, no exclusions, and no pointer to alternative tools for discovering skills you don't own.

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 no annotations, the description carries the full burden and does meaningful work: it discloses the non-obvious behavior that a 'hidden enrichment' payload accompanies each comment, spells out what that metadata blob contains (element purpose, DOM slice, viewport, console messages), and states the default filtering behavior. It could say more about pagination or the shape of the returned list.

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 action, with the parenthetical enumerations earning their space by describing non-obvious return content. Dense but not padded; only the default/filter clause overlaps with schema 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?

No output schema and no annotations, so the description must carry behavioral weight, and it does describe the returned fields and filtering default. Pagination via cursor is covered by the schema, but the description says nothing about result ordering or limits, leaving a small gap for a list 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 100%, so the schema already documents all four parameters including the status default and enum. The description's only added value is clarifying that 'all' means 'include resolved', which is marginal over what the schema provides; baseline 3.

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

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

States a specific verb+resource ('List comments left on a website') and goes further by enumerating the enrichment payload returned (page_path, target_selector, deployment_id, metadata blob). It does not explicitly differentiate from the sibling list_comments, so it stops short of a 5.

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

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

The description gives a filter default ('Defaults to open comments; pass status:all to include resolved'), which is usage of a parameter rather than when-to-use guidance. There is no explicit statement of when this tool should be chosen over list_comments or read_website, so usage is only implied.

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

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

No annotations exist, so the description carries the burden and does disclose meaningful traits: auth scope (the authenticated user's own websites), result ordering, and the exact return fields including the app URL path. It omits pagination behavior and limits, which the schema only hints at via cursor.

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, with scope/ordering front-loaded and the sibling redirect placed last. 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?

There is no output schema, so the description must describe returns, and it does: it enumerates id, name, framework, visibility, and the app URL pattern. Combined with the ordering and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents limit and cursor, giving a baseline of 3. The description adds no parameter-level detail (e.g., paging semantics, default page size) beyond what the schema states.

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 the authenticated user's websites) plus scope (own websites) and ordering (most-recently-updated first). It also names the sibling read_website with the distinction, so an agent can pick between them 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?

Explicitly routes agents to read_website for the live URL and production deployment, which is a clear when-to-use-this-instead signal. It gives no guidance on the other list_* siblings or on when listing is inappropriate, so it stops short of full conditional coverage.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses the exact return shape (id, title, description, URL, html, text), but says nothing about error behavior for a bad/missing id, permissions, or why both html and text are always returned despite the format flag.

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

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

Three tight sentences: what it does, what it returns, and a use case. Front-loaded with the action and zero filler.

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

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

With no output schema, the description correctly compensates by listing return fields, and the 100%-covered input schema covers parameters. The remaining hole is sibling disambiguation against get_report, which is material in a 44-tool namespace.

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

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

Schema description coverage is 100% and both parameters are documented there, so the baseline is 3. The phrase 'optionally as plain text' loosely maps to the format enum but adds no meaning beyond the schema's own 'Which content shape to emphasize. Both are always returned.'

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 ('Fetch a report by id') and even enumerates the returned fields, so the agent knows exactly what the tool produces. However, it never distinguishes itself from the sibling 'get_report' (nor from list_reports/search_reports), leaving the core selection question unanswered.

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 to read another agent's prior report as context' gives one scenario, which is more than nothing but far from explicit when/when-not guidance. With a near-identical sibling (get_report) in the toolset, the description should route between them and does not.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses an auth requirement ('Requires view permission') and what the response contains, but does not state error behavior (e.g., missing id), or what happens alongside the mutating sibling deploy_website.

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

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

Two short sentences, zero waste, with the resource and constraint front-loaded and the permission caveat second. Nothing is repeated or padded.

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

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

For a single-parameter read with no output schema, the description covers identity, scope, return contents, and a permission prerequisite. What is missing is minor: no pagination/error notes and no explicit relationship to list_websites or deploy_website.

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%: website_id is already documented as the website UUID. The description only echoes this with 'by id', adding no format, sourcing, or lookup hints beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a website'), constrains it to a single record ('by id'), and names the payload ('metadata plus its production deployment and live URL'). That distinguishes it from the plural list_websites sibling, though it never names that 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?

Usage is implied by 'by id' (call it when you already have a website id) and a prerequisite is stated ('Requires view permission'). However, it never says when to prefer this over list_websites or get_report, and gives no exclusions or alternatives.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says nothing about permissions, whether the reply notifies the thread participants, whether replies are editable/deletable, or the return shape — all relevant for a mutation tool.

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

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

A single short sentence, front-loaded with verb and resource. It earns its place but is terse to the point of adding no information the name already conveys.

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 low-complexity, two-parameter tool with full schema coverage and no output schema, the definition is minimally viable. It is nonetheless incomplete on routing between reply_to_comment and add_comment, and on any behavioral constraints.

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

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

Schema description coverage is 100% with only two parameters, both fully documented in the schema ('Reply text.', 'Parent comment id (UUID).'). The description adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb+resource ('Reply to an existing comment thread'), which is clearer than a tautology. However, it does not distinguish itself from the sibling 'add_comment', which an agent could easily confuse with replying.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternative. The only implied condition is that a parent comment must already exist, which is left for the agent to infer from the phrase 'existing comment thread'.

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 no annotations, the description carries the burden and does disclose the key side effect (comments are created on the report) and the return contract (per-reviewer ok / comments_created / error). It stops short of stating permission requirements, that this spawns LLM agents with associated cost/latency, or whether invocation is idempotent.

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

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

Two tight sentences: the action is front-loaded, followed by the return shape, then the when-to-use rationale. No filler or restated metadata.

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, and the description compensates by summarizing the per-reviewer outcome fields, while the 100%-covered input schema handles parameters. The only real gap for an annotation-free, potentially long-running agentic call is the absence of any note on permissions, cost, or expected duration.

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

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

Schema description coverage is 100%, so both report_id and reviewer_id are already documented, making 3 the baseline. The description marginally adds that the review runs against the current head revision, but it never mentions the single-reviewer option even though it leads with "every enabled agent-reviewer."

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 (run) plus resource (every enabled agent-reviewer) and the exact target (a report at its current head revision), so an agent knows this executes reviewers rather than configuring them. It is cleanly distinguishable from siblings like create_reviewer, update_reviewer, and list_reviewers.

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 when you've shipped a new revision and want a second agent to leave anchored critique before a human looks at it" gives an explicit triggering scenario that no sibling tool covers. It stops short of naming when-not-to-use or an alternative tool for narrower review needs.

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 no annotations, the description carries the burden and does well: it discloses the asynchronous/deferred behavior for skill-driven routines and prescribes polling list_routines for final status. It does not mention auth requirements or rate limits, so not a full 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 tightly written sentences, front-loaded with the core action. Every sentence earns its place: action, return value, and async caveat.

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, but the description explains the return payload (run outcome plus refreshed routine row). For a simple one-parameter tool this is nearly complete, with only minor gaps around error/failure behavior.

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 the sole routine_id parameter. The description adds no format or semantic detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Execute a routine immediately") with a precise qualifier ("without waiting for its next scheduled tick"). This clearly distinguishes it from sibling CRUD tools like create_routine, update_routine, and delete_routine.

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

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

Explains when to use it: to trigger a run now rather than waiting for the scheduled tick. It also routes the agent to list_routines for polling the final status. No explicit when-not guidance, but the 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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: the access scope (owned/invited/team-shared, not public links), the search semantics (trigram), and the return fields (id, title, snippet, share URL, similarity). It does not describe error behavior or result ordering by rank, so it is strong but not exhaustive.

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

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

Two sentences, zero filler. The scope constraint is front-loaded and the usage hint is placed last, which is exactly the right ordering for an agent scanning for intent then routing.

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 three-parameter search with no output schema, the description compensates by enumerating the returned fields and defining the visibility scope. Together with the fully-covered input schema, an agent has everything needed 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?

Schema description coverage is 100%, so limit, query, and include_html are already documented in the schema. The description adds no parameter-level detail (e.g., it never mentions include_html or the limit cap), so the schema does the heavy lifting and baseline 3 applies.

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

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

States a specific verb and resource ('Trigram text search over reports') and immediately scopes it to reports the caller owns, was invited to, or team-shares, explicitly excluding public share links. This is clearly distinguishable from siblings like list_reports and get_report.

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 an explicit when-to-use directive ('Use before drafting a new report to find prior work') and the scope exclusion clarifies when it won't find things. It does not name the alternative sibling (list_reports) for enumerating without a query, so it stops short of full alternative routing.

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

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

No annotations are provided, so the description carries the full behavioral burden. It doesn't state that this is a mutation, whether the change is reversible (it effectively is, given the open/resolved enum), what permissions are needed, or what happens to the thread's replies.

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

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

A single front-loaded sentence with no filler, and the two actions are stated up front. It is tight but arguably too terse for a mutation tool.

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 unannotated mutation tool with no output schema and incomplete schema descriptions needs the description to supply permissions, effects, and scope. It supplies none of that, and gives no hint about how it differs from set_website_comment_status.

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

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

Schema coverage is 50%: comment_id is documented in the schema, while status is only constrained by its enum. The description's 'resolve or reopen' implicitly maps to the resolved/open values, adding marginal value but nothing about id format beyond the schema's UUID note.

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

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

States a specific verb pair (resolve/reopen) and resource (comment thread), which maps cleanly onto the status enum. However, it does not distinguish itself from the close sibling 'set_website_comment_status', leaving the agent to guess which target scope applies.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as set_website_comment_status or reply_to_comment. The agent must infer usage purely from the name.

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

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

With no annotations, the description carries the full burden and does so: it states the manage-permission requirement (owner or admin), describes the side effect of re-sending visibility='domain' (list replacement), and discloses conditional runtime behavior — the embed only renders while the report is public, its link permission isn't 'none', and it has no share password.

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

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

Purpose is front-loaded and every sentence maps to a parameter or side effect, with no filler. However, it is one dense paragraph mixing six parameters plus return-value behavior, which would scan better as structured lines; the length is justified by the tool's complexity, not 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?

For a six-parameter mutation tool with no output schema, the description covers every parameter's semantics, the permission prerequisite, the embed rendering preconditions, and even the returned embed_snippet. An agent has everything needed 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?

Schema coverage is already 100%, so baseline is 3, but the description adds real semantic depth the schema lacks: it explains what each visibility value means to real audiences, that 'domain' requires allowed_email_domains, and that [] / null explicitly disables embedding. It also documents the embed_snippet return field.

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

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

Opens with a specific verb pair and resource: 'Publish or unpublish a report and control who can reach its share link (/p/:id)'. This is clearly distinguishable from update_report and the sibling set_report_signoff, which is referenced only for the staged-publishing concept.

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 conditional recipes: 'To publish a report so anyone can open and comment on it, set visibility="public" and public_permission="comment"', and 'To change the domain list, send visibility="domain" again with the full new list'. It also cross-references set_report_signoff for staged publishing. It stops short of naming an alternative tool for overlapping edits (e.g. update_report), so it is strong but not exhaustive.

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 no annotations, the description carries the full burden and does so well: it discloses replacement semantics, the one-verdict-per-reviewer constraint, revision pinning at submission, and staleness when report content changes. It omits auth/permission requirements (e.g. must the caller be a reviewer?) and error behavior, which keeps it from a 5.

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

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

The core action and target are front-loaded in the first clause, with the optional note following, and the second sentence is dense but entirely substantive state semantics. Every sentence earns its place 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 mutation tool with no annotations and no output schema, the description covers the important behavioral surface (replace, cardinality, snapshot/staleness). It stops short of describing return values or permission prerequisites, leaving a small but real gap.

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

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

Schema description coverage is only 67% and the verdict property has no schema description, so the description usefully supplies the two accepted values and constrains the note to a 'one-line' short string. It adds real meaning beyond the schema, though report_id is left to 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 pair ('submit or replace') and an exact resource ('your review verdict on a report'), plus the allowed verdict values. An agent can distinguish this write tool from read-side siblings like get_report_signoffs and from adjacent actions like request_review or set_comment_status without opening a schema.

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

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

The 'submit or replace' framing makes the upsert semantics clear and tells the agent it does not need a separate delete/update step. It conveys clear usage context (one verdict per reviewer per report) but names no alternative tool and states no when-not-to-use condition, 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?

No annotations are provided, so the description carries the full behavioral burden. It does not disclose whether the change is reversible (only implied by 'reopen'), whether resolving notifies the comment author or reviewers, whether the comment is hidden versus merely flagged, or what permissions are required for a mutation.

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

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

Two compact sentences with the core action front-loaded and the usage hint trailing. No filler, though the second sentence is thin enough that it could have carried more specificity without becoming bloated.

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 and no annotations, the definition covers the basics but leaves success/return behavior and side effects unstated. Adequate but with clear gaps given the absence of structured behavioral hints.

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

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

Schema coverage is 50%: comment_id is documented, status is an enum with self-explanatory values. The description's value-add is mapping 'reopen' to the 'open' enum value, which helps an agent pick the right string, but it adds no other parameter detail.

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 pair (resolve/reopen) applied to a specific resource (website comment), which is more informative than the name alone since 'set_status' does not reveal the two available transitions. It implicitly separates this from the sibling set_comment_status by scoping to website comments, though it never names that 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?

"Use this to close out issues as you ship fixes" gives an implied workflow context for the resolve direction, but says nothing about when to reopen, when to prefer set_comment_status or reply_to_comment, or any prerequisites. Usage is suggested rather than specified.

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?

No annotations are provided, so the description carries the full behavioral burden. 'in place' implies mutation and the at-least-one-field rule is disclosed, but there is no information on permissions, whether edits are reversible, how unspecified fields are treated, or the null-to-clear semantics (which live only in the schema).

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

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

Two tightly written sentences with zero waste. The mutation action is front-loaded and the constraint sentence follows logically.

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 no annotations and no output schema, the description covers the action and one constraint but omits behavioral aspects like permission requirements and handling of unmentioned fields. High schema coverage (88%) partially compensates, keeping this adequate but not 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 description coverage is 88%, so the schema already documents parameters (including null-to-clear semantics) thoroughly; baseline 3 applies. The description names some mutable fields but adds no syntax or format detail beyond what the schema provides.

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

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

Clear verb ('Edit') + resource ('report') + enumerated mutable fields (title, description, HTML, producer attribution). An agent can distinguish it from create_report/get_report without opening the schema, though it doesn't explicitly name a sibling as the alternative.

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

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

The only guidance is the validation constraint that at least one mutable field must be provided. There is no when-to-use context, no mention of the read/create/delete siblings, and no prerequisites such as ownership or permissions.

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 no annotations, the description carries the full behavioral burden. It usefully discloses an authorization constraint ('you own') and non-obvious semantics ('null clears') for two fields, which goes beyond the schema. However, it omits error behavior, interaction between fields, and any return/auth-header handling detail for a mutation tool.

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

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

Two sentences, zero filler, first sentence front-loads the action and ownership scope, second enumerates the mutable fields. Every clause contributes 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 7-parameter mutation tool with no annotations and no output schema, the definition covers the fields and clearing semantics adequately. It leaves gaps around permissions beyond ownership and the effect of toggling enabled/auto_on_revision, so it is viable but not thorough.

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 only 14%, so the description must compensate, and it does: it enumerates six of the seven updatable fields and explains the null-clears semantics for prompt and reviewer_auth_header, which the schema's nullable types alone do not convey. Only reviewer_id is left to the schema, which documents it.

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

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

States a specific verb+resource ('Update an agent-reviewer') and adds a scope qualifier ('you own') that distinguishes it from the bare CRUD siblings. It does not explicitly name create_reviewer/delete_reviewer as alternatives, but the action word makes the distinction 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?

The phrase 'Pass any subset of ...' implies partial-update usage semantics, which is genuine guidance, but there is no explicit when-to-use vs. when-not-to-use or routing to siblings. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the ownership requirement, the important null-clears semantics for trigger_url, trigger_auth_header, and skill_id (versus omitting a field), and the side effect that changing schedule_cron recomputes the next run time and is re-validated against a plan floor. It omits failure/error behavior and whether connector_ids replaces or merges, which keeps it off 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?

Two sentences, front-loaded with the action and ownership, with the parameter list and the schedule_cron side effect following. Dense but every clause earns its place; the parenthetical '(null clears)' notes are load-bearing.

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 nine-parameter mutation tool with no annotations, no output schema, and 11% schema coverage, the description covers nearly all parameters and the key side effect. It leaves some error/return expectations and connector_ids replacement semantics unstated, but an agent has enough 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?

Schema coverage is only 11%, so the description must compensate, and it largely does: it enumerates all eight optional parameters and clarifies the null-clears behavior that the bare schema cannot express. Gaps remain for payload structure and whether connector_ids is a full replacement or a merge.

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 ('Update a routine') and adds an ownership scope ('you own') that distinguishes it from sibling mutations like create_routine, delete_routine, and run_routine. It stops short of explicitly naming those siblings as alternatives, but the verb 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?

'Pass any subset of...' gives real guidance on partial-update invocation, and 'a routine you own' implies the prerequisite. However, there is no explicit statement of when to reach for this tool versus create_routine/run_routine/delete_routine, so routing is only implied.

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

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

With no annotations, the description carries the full burden and does disclose key behaviors: the returned url is a stable public link, the tool is idempotent-by-path ('Re-uploading the same relative_path replaces the previous asset'), and both raw base64 and data-URL inputs are accepted. It omits permission requirements (present only in the schema) and rate/size limits, keeping it short of full coverage.

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

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

Purpose is front-loaded in the first sentence, followed by return-value guidance and input/replacement notes. Four tight sentences with minimal waste, though the URL-usage sentence is slightly padded.

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

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

For a mutation tool with no annotations and no output schema, the description usefully explains the return value (stable public url and where it can be embedded) and the replacement semantics. Authorization and size limits live in the schema and keep it from being fully self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates what the schema already says about content_base64 (raw base64 or data URL), adding no new syntax or constraint details 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?

States a specific verb ('Attach') and resource ('binary asset') against the target report, with concrete examples of asset kinds (image, video, font, CSS, JS). An agent can tell this is the upload counterpart to siblings like delete_report_asset and list_report_assets, though no sibling is named explicitly.

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

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

The description implies when the tool is used (to make a binary referenceable inside report HTML) but never states when to prefer it over alternatives or any exclusions. The re-upload clause gives operational context but not selection guidance.

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