Stomio

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

Annotations only declare readOnlyHint=false and destructiveHint=true; the description adds substantial context beyond that: the target user is notified by email and in-app, their workspace role is unchanged and viewers stay read-only, and the first call is a no-op preview. It also discloses token behavior (single-use, short-lived), which an agent cannot infer from the annotations.

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

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

Front-loads the action and prerequisite, then the critical two-step protocol, with no filler sentences. It is dense and slightly repetitive with the schema's confirmationToken description, which is why it stops short of 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?

Covers prerequisites, side effects (notifications), safety caveats, and the confirmation flow, which is strong for a 3-parameter mutation. However, with no output schema, it never says what the preview or success response contains (e.g., what fields the agent should surface to the user), leaving a gap for a two-step approval workflow.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema cannot convey: confirmationToken must be paired with the SAME arguments, is single-use, and expires after a few minutes. It also cross-references where valid userId values come from (listOrganizationUsers / listBetaManagers).

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: 'Assigns a workspace member as a manager of this beta project.' That is clearly distinguishable from siblings like removeBetaManager, listBetaManagers, and inviteTesters, so an agent can select it without opening other schemas.

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

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

Gives both prerequisites ('must already be a member of the workspace (see listOrganizationUsers)') and an explicit exclusion ('inviting new members to the workspace is not possible over MCP'), pointing to the right alternative. It also spells out the two-step when-to-call sequence: first without a token to get a preview, then again only after explicit user approval.

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

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

Beyond the annotations, it discloses important behavior: allowed and unsupported question types, the pre-live constraint, the readiness validation that blocks publishScreeningForm, and the auto-review linkage by questionId. The annotations only provide basic mutation hints, so this added operational context is substantial.

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

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

The description is front-loaded and efficient for a tool with complex authoring rules. It contains useful constraints and only a small amount of meta-guidance about interpreting the ready flag, which is justified by the behavior it describes.

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

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

For a complex authoring tool, it covers the key prerequisites, timing window, allowed types, readiness validation, and follow-up actions. It only lightly implies the return value via questionId and does not fully explain the response shape, but the core invocation context is present.

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

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

Schema description coverage is 100%, and the input schema's content property already documents type-dependent content rules extensively. The description mainly reiterates the allowed types and readiness behavior rather than adding new parameter-level semantics beyond the schema.

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

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

The description names the exact verb and resource: 'Adds a question to this beta project's screening form (the public application form).' It also distinguishes the tool from publishScreeningForm and getScreeningSetup by explaining the authoring phase and prerequisites.

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 clearly states when the tool is usable: only BEFORE the form is live, after the screening setup exists. It also points to publishScreeningForm as the next step, but it does not explicitly route edits to updateScreeningQuestion or deletes to deleteScreeningQuestion.

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

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

Annotations declare destructiveHint=true, and the description adds substantial context beyond that: exactly which resources are frozen, which remain mutable (invitations, applicant review, labels, announcements, NDA bypass, ticket conversation), and that manager addition still works. It also discloses side effects like tester notifications being removed and managers being emailed, plus token single-use and expiry 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?

The description is front-loaded with the core action and effects before the freeze list and two-step instructions. The freeze/no-freeze enumeration is long but each item carries real behavioral information; only minor trimming would improve it.

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

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

For a destructive, two-step mutation with no output schema, the description covers consequences, invariants (cannot archive a finished beta), reversibility, the full confirmation workflow, and token lifetime. An agent has everything needed to call it safely and correctly.

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

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

Schema description coverage is 100%, so both productId and confirmationToken are already documented in the schema. The description reinforces the two-step token workflow (omit first, resend with same arguments), but adds no syntax or format detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Archive this beta project') and immediately enumerates the concrete effects (notifications removed, managers emailed, screening form closed). It is clearly distinguished from siblings like pauseBeta and restoreBeta through the freeze/no-freeze breakdown.

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

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

It states a hard precondition ('A finished beta cannot be archived'), names the reversal tool ('Reversible with restoreBeta'), and gives an explicit two-step invocation protocol with when to call with and without the token. Nothing about when to use this tool is left to inference.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description adds concrete consequences the agent cannot infer: a cap of 100 withdrawals per call, no email notification to anyone, cancelled:false plus no-op for unmatched targets, and scope limited to one beta project. These are exactly the operational details an agent needs before performing a destructive action.

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 key constraint (what is withdrawn and where targets come from) is front-loaded, and every sentence carries information. It is a single dense paragraph with stacked em-dash clauses, which is slightly harder to scan than a short bulleted structure would be.

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, yet the description still explains the meaningful return signal (cancelled:false for non-matching targets). Combined with the source of targets, the 100-item cap, and the interaction with removeTester, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and each parameter is documented, but the description adds cross-parameter meaning absent from the schema: emails only work for addresses listPendingInvitations reports while invitationIds work for every invitee, the two inputs combine freely, at least one is required, and naming the same person both ways counts as one target. That is genuine added value, though per-field detail largely duplicates the schema.

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

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

States a specific verb and resource scoped precisely: "Withdraws THIS beta project's pending tester invitations." The emphasis on THIS and pending separates it from removeTester and from actions on other beta projects without requiring the agent to open a sibling schema.

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

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

Explicitly routes the agent to listPendingInvitations as the source of targets, and names the alternative for a related case ("people who already accepted and became testers are unaffected (use removeTester for those)"). It also states the exclusion that invitations to OTHER beta projects are untouched, so when-to-use and when-not-to-use are both covered.

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

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

Beyond the annotations, the description discloses important behavior: testers are not notified, deleted tasks or steps permanently delete tester answers, attachments, and completion records, and totalTasks is the post-commit beta task count rather than a change count. It also explains single-use, expiring confirmation tokens and concurrent-change failure behavior, which materially improves safe invocation.

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 long but front-loads the core action and uses clear sentences for blocking conditions, destructive effects, totalTasks semantics, and the two-step flow. Some wording duplicates the confirmationToken schema description, keeping it just short of maximally concise.

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 important response semantics via totalTasks and the preview/token flow. For a destructive two-step mutation with only two parameters, it gives enough context about permissions-like constraints, side effects, and concurrency 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 both parameters are already documented in the schema. The description mostly repeats the two-step confirmationToken usage already present in the schema and adds little new parameter-level meaning beyond noting token expiry in minutes rather than merely 'short-lived'.

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

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

The description states a specific verb and resource: it publishes ALL staged task and step changes of the beta project to its testers. It also distinguishes the operation from a live beta publish by describing it as the equivalent of Stomio's Publish button and by emphasizing staged versus live changes.

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 explicit: call without confirmationToken first to preview, show the preview to the user, then call again with the same arguments plus the token only after explicit approval. It also gives when-not conditions, such as blocked publish when a staged task has no steps, and the need to preview again if the staged set changed.

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

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

Goes well beyond destructiveHint=true by spelling out exactly what is destroyed: enabled:false permanently deletes the link, holders can no longer join, and re-enabling mints a different link while the old one stays dead. It also discloses the publish-state gating of link visibility, which annotations cannot convey.

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

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

Purpose is front-loaded and the two irreversible branches are explained crisply, but the dense run-on sentence packs several independent facts together and repeats schema-level details (50-domain cap, empty list behavior) that an agent already gets from the parameters.

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

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

For a three-parameter mutation with no output schema, the description covers everything an agent needs to act safely: required parameter combination, permanence of deletion, link regeneration, domain semantics, and the publish-state dependency of the resulting link.

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 description largely restates the schema's enabled and allowedDomains meanings (including the 50-domain cap and empty-list behavior). It does add one real cross-parameter rule not expressible in the schema — at least one of enabled/allowedDomains must be provided — but most of the per-parameter text duplicates 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?

Opens with a precise verb+resource: 'Configure this beta project's public opt-in join link.' It is clearly distinct from nearby siblings like configureScreening or setInvitationEmail, and even names the related read surface (getProductOverview exposes optInLink).

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

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

States the precondition that at least one of enabled/allowedDomains must be supplied, explains the true vs false branches, and clarifies that configuring on a draft is valid and the link only goes live at publish/running/paused. It does not explicitly redirect to a sibling for viewing the link, but the operational 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?

Goes well past the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that the first call creates three entities plus an empty form, that active=false pauses applications without deleting anything, and that configuring 'sends nothing and notifies nobody.' The empty-string restore behavior for the thank-you copy is also spelled out.

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

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

Front-loaded with the action, then the create/author/publish workflow, then parameter caveats. Dense but every clause carries operational information; nothing is repeated from the schema verbatim.

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

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

For a four-parameter mutation tool with no output schema, the description covers creation side effects, ordering constraints, public-link gating, and non-notification guarantees. An agent has everything needed to call it correctly and in the right order.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by attaching consequences to parameters — active gates the link without deletion, and empty strings restore default copy. It stops short of adding anything for productId beyond what the schema already says.

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 or update this beta project's applicant screening setup.' It also names the sibling tools it hands off to (addScreeningQuestion, publishScreeningForm), so an agent can separate it from the question-level and publish-level tools immediately.

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

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

Explicitly gives the sequence: first call creates source/pool/empty form, then author questions with addScreeningQuestion, then publish via publishScreeningForm, and notes the public link only accepts applications once live. That is a when-to-use and what-happens-next chain with no inference required.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses that existing applicants are re-evaluated immediately on creation and that refreshedCount reports how many suggestions changed — non-obvious side effects an agent must anticipate. It also makes the non-destructive scope explicit: suggestions never invite or reject anyone.

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

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

The description is front-loaded with purpose and match semantics before drilling into condition grammar, which is good ordering. It is dense and slightly repetitive — the ALL-conditions match rule is stated twice — and embeds a schema-like structure in prose rather than relying on the input schema.

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

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

For a write tool with no output schema, it covers prerequisites, match semantics, per-field condition grammar, downstream effects, and even names the return field refreshedCount. An agent has everything needed to construct a valid call and anticipate its effects.

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%, but the description goes well past it by fully specifying the condition object grammar (type, operator, questionId, value) and constraints the schema only hints at: questionId required for type "question", "contains" unsupported for emailDomain, "exists" takes no value, and gt/lt are numeric and question-only. This is meaning the schema alone does not supply.

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

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

The first sentence names a specific verb and resource ("Create an auto-review rule") and scopes it to this project's applicant screening, which cleanly separates it from updateApplicantRule and deleteApplicantRule in the sibling list. It immediately explains what the rule does downstream (suggested status + labels on match).

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

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

It states the prerequisite (screening setup must exist, pointing to getScreeningSetup / configureScreening) and clarifies the rule only produces suggestions that a manager still reviews via reviewApplicants. It does not explicitly say when to use create versus updateApplicantRule, so a small routing gap remains.

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

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

Annotations only say non-readonly, non-destructive; the description adds real behavioral context: the caller becomes manager, AI features are auto-enabled, and the project stays invisible to testers until published. It does not state what the call returns or what happens on a duplicate name (the schema hints name is unique), 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?

Front-loaded with what the tool creates and the resulting state, then the workflow. Most sentences carry information, though a phrase like 'so it is immediately usable with the other tools' is mildly redundant with the AI-features sentence.

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

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

For a 6-parameter creation tool with no output schema, the description covers lifecycle position, ownership, visibility, and defaults well. The one real gap is the return value (e.g. the created beta's identifier), which an agent would need to chain into createTask or publishBeta.

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 cross-parameter semantics the schema cannot: only name is required at creation and every other field can be supplied later via updateBetaDetails. It does not elaborate on the boolean defaults, which the schema already covers.

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 new beta project') plus the resulting state ('as a draft') and the effect on the caller ('You become its manager'). This distinguishes it clearly from sibling mutations like duplicateBeta, archiveBeta, or restoreBeta.

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

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

Gives an explicit ordered workflow naming the actual sibling tools (createBeta -> createTask -> createStep -> inviteTesters -> publishBeta/launchBeta), and even branches on schedule-vs-start-now. It also states the minimum viable call ('Only name is needed').

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

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

Annotations only declare non-read-only, non-destructive. The description adds real behavioral context beyond that: passing categoryName can create a new category as a side effect, uniqueness is enforced project-wide (implying duplicate-name failures), color is auto-assigned from a palette when omitted, and the whole operation is manager-internal and sends no notifications. It stops short of saying what happens on a partial failure or duplicate 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?

Front-loaded with purpose, then relationships, then parameter rules, then side-effect caveats — a logical progression. It is somewhat long and repeats the color/hex detail already in the schema, but no sentence is pure filler.

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

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

For a 6-parameter nested-array creation tool with no output schema, the description covers workflow, uniqueness, category creation side effects, and notification behavior well. The notable gap is the return value — with no output schema, an agent does not learn whether created label IDs or categories are returned.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds meaning: it clarifies that name uniqueness is 'across the whole beta project, not just the category' (sharpening the schema's looser wording) and frames categoryName as a reuse-or-create switch rather than a plain string.

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

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

Opens with a specific verb+resource+scope: 'Creates labels in this beta project, inside one label category (existing or new)'. It immediately distinguishes itself from updateBetaLabel/deleteBetaLabel and from manageTaskLabels/manageTesterLabels by explaining that this tool creates the label entities those tools merely assign.

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

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

Gives explicit sequencing guidance ('create the labels here first, then label the testers and the tasks') and routes the agent to siblings: listBetaLabels for existing category IDs, manageTaskLabels/manageTesterLabels for assignment. It also states the either/or rule for categoryId vs categoryName, so an agent knows how to choose between the two paths.

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

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

Beyond the annotations, which only declare this as a non-read-only, non-destructive mutation, the description discloses substantial behavior: staged versus live changes, staged-id responses with liveVersionId links, TriggeredEmail sending semantics and timing, audience routing constraints, and edit restrictions on finished or archived projects. This is exactly the kind of operational context annotations do not provide.

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

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

The description is front-loaded and organized, with the core append behavior and staging model stated early. However, it is very long and repeats TriggeredEmail and content-shape details that are also present in the schema, reducing conciseness for an already complex definition.

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

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

Given the tool's complexity, including staging semantics, TriggeredEmail rules, audience restrictions, and extensive content validation, the description is complete enough for an agent to call it correctly. The absence of an output schema is mitigated by the description's note that responses return staged rows and unexpected ids.

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

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

Schema description coverage is 100%, and the description largely restates the detailed schema guidance for content, type, text, and audience fields rather than adding substantial new parameter meaning. It does add useful cross-references and behavioral context, but the parameter-level semantics are already carried by the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: it adds a step to a task and appends it to the end of that task's step list. It distinguishes the special TriggeredEmail step type and points to sibling tools such as updateStepsOrder and commitTaskChanges, so 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?

It explicitly tells the agent to create steps in tester order because creation always appends, and to use updateStepsOrder to reorder afterwards. It also explains immediate application on draft/scheduled projects versus staged changes on running/paused projects, names commitTaskChanges and revertTaskChanges as the publishing/discarding alternatives, and states that finished or archived projects cannot be edited.

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

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

With annotations only saying this is a non-read-only, non-destructive mutation, the description adds substantial behavior beyond them: staging on running or paused projects, the need for commitTaskChanges to publish, revertTaskChanges to discard, and getBetaTasks with version 'unpublished' to inspect staged state. It also explains that responses return staged ids with liveVersionId links, and that ready=false after creation is expected rather than an error.

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

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

The description is front-loaded with the creation action and appending behavior, then moves into step guidance and staging semantics. It is longer than typical but dense with operational detail; most sentences carry necessary context, though the staging paragraph is quite dense.

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

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

For a mutation tool with no output schema, the description covers the important response behavior (ready=false, staged ids, liveVersionId), lifecycle edge cases (draft versus running projects, archived projects), and next-step guidance. It gives an agent everything needed to invoke the tool correctly in context.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds useful cross-parameter meaning: optional and availableDate are mutually exclusive, and optional only works for Stomio-placement beta projects. It also clarifies ordering behavior around availableDate, though most individual field semantics remain 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?

The description states a specific verb and resource: creates a new task in this beta project and appends it to the end of the task list. It also distinguishes the tool from siblings by directing step creation to createStep and reordering to updateTasksOrder, so an agent can identify its unique role.

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

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

It gives explicit when-to-use context: create tasks in tester order because creation always appends, use updateTasksOrder for later placement, and use createStep to add steps. It also explains lifecycle constraints: edits are immediate on draft or scheduled projects, staged on running or paused projects, and blocked for finished or archived projects.

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

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

Annotations only declare it is a non-read-only, destructive write. The description goes far beyond: it discloses notification side effects (email + in-app to the tester, or to managers), that Slack/Webex/Zapier/Jira integrations fire with only jiraSyncFailed reported back, the active-project precondition, and the two-step preview/confirm semantics with single-use expiring tokens.

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

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

Dense but efficient: behavior type split, side effects, precondition, return-value caveat (code absent on chat tickets), and the two-step protocol are each covered in one or two sentences with no filler. Minor redundancy with the schema on the token being 'single-use and short-lived,' but nothing that wastes meaningful space.

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 with no output schema and heavy side effects, the description covers everything an agent needs: preconditions, the write's blast radius, which failures surface (jiraSyncFailed), and what 'code' means in the response. The two-step confirmation protocol, the most likely source of misuse, is spelled out explicitly.

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 every parameter including enum values and conditional userId requirements. The description reinforces that userId is the single tester's id from getBetaTesters and that it is required only for chat, but adds little beyond what the schema already states, 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 opening sentence names a specific verb and resource ('Creates a ticket in this beta project') and immediately splits the resource into two distinct behaviors (chat vs. internal ticket), which is exactly what an agent needs to distinguish it from siblings like updateTicket, replyToTicket, or makeTicketPublic.

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

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

It states explicit when-to-use conditions ('chat' only to open a direct conversation with one tester; every other type for internal tickets), hard preconditions ('the beta project must be running — paused is not enough'), and a mandatory call sequence. Alternatives are not named by tool name, but no ambiguity remains about which path to choose.

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

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

Goes well beyond the destructiveHint annotation: it discloses that existing applicants are immediately re-evaluated, that APPROVED reviews are never affected, and that the operation is irreversible. This is the side-effect information an agent needs before invoking a destructive 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?

Three tight sentences, front-loaded with the action and scoping, followed by consequences and recoverability. No filler or repetition.

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

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

With no output schema, the description helpfully explains the refreshedCount return value; combined with the mutation semantics and recovery path, nothing material is missing for a two-parameter destructive 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%, with both ruleId and productId documented including provenance (getScreeningSetup, listProducts). The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete an auto-review rule') and narrows scope to 'this beta project's applicant screening', which cleanly separates it from deleteScreeningQuestion, deleteStep, and updateApplicantRule.

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

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

Implies the use case (removing an unwanted screening rule) and points to createApplicantRule as the recovery path, but never states the alternative for modifying rather than removing a rule (updateApplicantRule), leaving that routing to inference.

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

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

Goes far beyond the destructiveHint annotation: it enumerates every assignment that is removed (testers, tasks, pending invitations, screening-rule suggested labels), discloses irreversibility, the surviving category, no notifications, immediate effect on live and staged tasks, and the optimistic-concurrency failure mode where the confirm fails if assignments changed since the preview.

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

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

Dense but front-loaded: the destructive scope comes first, the consequence for task visibility second, and the two-step protocol last. The capitalised 'TWO-STEP TOOL' block is heavy, but nearly every clause carries operational information rather than filler.

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

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

No output schema exists, and the description compensates by explaining what the first call returns (a preview plus a confirmationToken) and what happens on the second. The main uncovered detail is the preview's payload shape, which an agent would otherwise only discover at runtime.

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

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

Schema description coverage is 100%, including the confirmationToken field, so the baseline is 3. The description reinforces the token lifecycle (single-use, expires after a few minutes, same arguments required) but adds little meaning about labelId or productId beyond what the schema already says.

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 and resource ('PERMANENTLY deletes one label of this beta project') and immediately bounds scope by noting 'the label's category survives it', which separates it from deleteBetaLabelCategory and updateBetaLabel. An agent knows exactly which entity is destroyed without opening a schema.

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

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

Gives explicit invocation conditions for the two-step flow (call without confirmationToken, show preview, get user approval, re-call with the same arguments) and a re-preview condition when underlying assignments change. It does not explicitly route to sibling alternatives such as updateBetaLabel for non-destructive edits or manageTaskLabels for per-task removal, so the when-not guidance is implied rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds substantial context beyond them: irreversibility, the failure message naming in-use labels, that nobody is notified, conditional-confirm failure on changed category contents, and token single-use/expiry. The only minor gap is no detail on the preview payload's shape, though that is largely inferable.

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 destructive consequence, then failure modes, then the two-step protocol, with zero filler sentences. Slight redundancy exists because the two-step confirmation flow is restated in the confirmationToken schema description, making the long final paragraph partly duplicative.

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, irreversible mutation with no output schema, the description covers everything an agent needs: preconditions, alternatives, failure behavior, notification semantics, and the full preview/confirm lifecycle including race conditions and token expiry.

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

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

Schema coverage is 100%, so the schema already documents all three parameters; the description still adds meaning by requiring the 'SAME arguments' on the confirm call and by tying token validity to the previewed label set. That goes beyond the schema's generic 'single-use and short-lived' 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 and resource ('PERMANENTLY deletes one label category ... along with the labels inside it'), which distinguishes it from the sibling deleteBetaLabel (single label) and updateBetaLabelCategory. Scope and side effect (labels inside are removed) are explicit in the first sentence.

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

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

Names the preconditions for success (no label assigned to a tester, task, or pending invitation) and the exact alternatives for clearing blockers: manageTesterLabels, manageTaskLabels, or deleteBetaLabel. It also spells out the required two-call sequence and the re-preview requirement if a label is added mid-flow.

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

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

Annotations already declare destructiveHint=true, and the description goes beyond them by disclosing the cascade: referencing auto-review rules lose that condition and empty rules are deleted, mirroring app behavior. The mention of rulesTouched also hints at side-effect reporting. It does not state error behavior when the form is live (rejection vs. no-op), leaving one meaningful gap.

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

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

Three tight sentences, front-loaded with the core action and constraint before the cascade detail. 'Exactly like the app' is slightly informal but conveys that the behavior matches the UI, which is useful. No filler.

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

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

With no output schema and only two required params, the description covers what an agent actually needs: the precondition, the destructive cascade, and the meaning of the rulesTouched field. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, and both parameters carry their own descriptions including the 'Never invent ids' warning, so the description adds nothing about parameter meaning. Baseline 3 applies since the schema does the work.

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 ('Deletes a screening form question'), which cleanly separates it from sibling deletions like deleteStep, deleteTask, and deleteApplicantRule. The added precondition sharpens rather than muddies the purpose.

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

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

Gives a hard usage boundary: only usable before the form is live, which is the decisive gating condition an agent needs. It does not explicitly point to updateScreeningQuestion or configureScreening as the alternative when the form is already live, so it stops just short of full routing guidance.

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

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

Goes well beyond the destructiveHint=true annotation by disclosing cascade destruction of answers and uploads, the triggered-email refusal rule, and the staging model on running/paused projects. It also warns that responses return staged rows with ids the caller did not pass in. It loses a point only for not clarifying how long staging persists or whether the refusal is checked at delete time or commit time.

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 destructive consequence and well organized into constraint, workflow, and id behavior. However, the final sentence restates the staging point already made earlier ('On a running or paused beta project the deletion is only STAGED'), which is redundant and could be merged.

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

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

For a 3-parameter mutation tool with no output schema, the description covers destruction scope, preconditions, project-state branching, the staging lifecycle, and id echo behavior. An agent has everything needed to call it correctly or to know it should defer to commitTaskChanges.

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 would be 3, but the description adds real meaning not in the schema: during staging both the live id and the staged id are accepted, and the response echoes the staged id with liveVersionId linking back. That is actionable id-semantics an agent would otherwise get wrong.

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 ('Deletes a single step from a task') and immediately scopes it apart from siblings like deleteTask, updateStep, or removeStepMedia by making clear it removes the step and all its submitted answers and uploads.

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

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

Gives explicit when-not conditions (refused if it would leave a triggered-email step first; blocked entirely on finished or archived projects) and names the exact alternatives for the staged workflow: commitTaskChanges to publish, revertTaskChanges to discard, getBetaTasks with version 'unpublished' to inspect.

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

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

Annotations only declare destructiveHint=true; the description goes far beyond by disclosing the exact blast radius (all steps plus tester answers, uploads and completion records are destroyed), the staging vs immediate application rules, and that the commit — not this call — is the point of no return. It also warns that responses return STAGED rows with unexpected ids and liveVersionId, which is non-obvious behavior an agent would otherwise misread.

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 critical facts are front-loaded (permanent deletion, cascade, cannot-edit archived), but the staging rule is stated twice ('the change is STAGED' near the top and again in the final sentence about the answers being destroyed at commit), and the id-handling paragraph is somewhat tangential to the delete action itself. It is dense and mostly earns its space, but the repetition and length work against scannability.

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 two-parameter mutation with no output schema, the description covers everything that matters: consequences, reversibility window, environment-dependent behavior, id semantics, and the blocked-state exclusion. Nothing an agent needs to call this safely 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 already 100%, so the baseline is 3. The description adds real meaning beyond the schema by explaining that while staging, both live and staged ids of a task are accepted but the response always carries the staged row — context the parameter docs do not provide.

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 ('Deletes a task from this beta project') and immediately scopes it against siblings by explaining the cascade (steps, answers, uploads, completion records), which distinguishes it from deleteStep and archiveBeta without requiring schema inspection.

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

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

It explicitly names the conditions that change behavior (draft/scheduled = immediate; running/paused = staged), names the alternative tools that govern the staged outcome (commitTaskChanges, revertTaskChanges, getBetaTasks with version 'unpublished'), and states a hard exclusion: content of finished or archived beta projects cannot be edited.

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

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

Annotations only tell the agent this is a non-read, non-destructive write. The description goes far beyond that with an explicit copied/not-copied inventory (testers, invitations, tickets, results, labels, managers, ticket code prefix, objectives, NDA, opt-in link, custom invitation email) and states the resulting state: a draft, AI features enabled, owned by you. That is exactly the kind of side-effect disclosure a mutation tool needs.

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

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

Front-loaded with the action, then the copied/not-copied inventories and the end state. The enumerated exclusion list is long but each item prevents a real surprise about missing data, so it earns its space; the closing sentence about ownership and usability is slightly redundant but still informative.

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 mutation with no output schema, the description covers side effects, resulting state, and ownership thoroughly. The main gap is the return value: the agent is not told that a new productId comes back, which matters because every sibling tool needs an ID and there is no output schema to fall back on.

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 all four parameters are already documented, including the 'override the copied X requirement' semantics. The description only alludes to them generically ('override them with the optional arguments') and labels them 'tester onboarding flags', which is a slightly different framing from the schema's custom-fields/shipping-info wording, so it adds little beyond the structured data.

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 new draft beta project as a copy of this one') and immediately establishes the scope as a duplication rather than a from-scratch creation, which cleanly separates it from createBeta in the sibling list. An agent can tell what it produces (a draft copy) 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?

Clear context for when to use it (copying an existing project) and a useful post-condition ('immediately usable with the other tools'). It does not explicitly name createBeta as the from-scratch alternative or state exclusions such as 'do not use for cross-workspace copies', so it stops short of full routing guidance.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description goes well past that by declaring the flag is a manager-only bookmark, the tester is not notified, the answer keeps counting in every result, and nothing changes for anyone else. Those are exactly the non-obvious consequences an agent needs before mutating state.

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 behavioral constraint is front-loaded in the first sentence, followed by effect and then id provenance. Slightly long, and the answerId sentence duplicates the schema description of the same field, 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 three-parameter mutation with no output schema, the description covers effect, side-effect visibility, notification behavior, and input provenance. It stops short of stating idempotency (flagging an already-flagged answer) or error behavior for an invalid or non-flaggable answerId, which would fully close the loop.

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 productId, answerId and flagged are already documented, and the description's answerId provenance sentence is repeated almost verbatim from the schema. It adds no new syntax, format, or edge-case meaning beyond what structured fields provide, 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?

"Flag or unflag one tester answer in this beta project" gives a specific verb pair, a single-resource scope, and an owning entity (beta project). It is immediately distinguishable from listFlaggedAnswers, which reads the flagged set rather than mutating it.

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 states the precondition that governs invocation: answerId values only exist for free-text, file, instructions and ranking entries, while choice and rate steps expose per-option counts and no answer ids. It also points to listFlaggedAnswers and notes that every answer entry in results already carries its flagged state, telling the agent when it does not need this tool to inspect flags.

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

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

Annotations only declare readOnlyHint, so the description carries the rest — and it does: images return as viewable content, other types return metadata plus a time-limited download URL, and URLs change on every call while resourceId is the stable identity. The anti-retry instruction is exactly the kind of behavioral detail annotations cannot express and prevents a common agent failure loop.

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

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

Front-loaded with purpose, then return-shape behavior, then the retry caveat — a sensible escalation. It is denser and longer than a two-sentence ideal, but no sentence is redundant or repeats structured fields.

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

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

For a two-parameter read tool with no output schema, the description covers what comes back in each case, how to pass the URL along, and the retry pitfall. Nothing an agent needs in order to call it correctly and interpret the result 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; the description adds genuine meaning by framing resourceId as a stable identity sourced from answer resources. productId is left entirely to the schema, which is acceptable given its own description points at listProducts.

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 one file uploaded by a tester as a step answer") and pins provenance by saying the resourceId comes from getTaskResults or getStepResults. It does not explicitly differentiate itself from attachment/media siblings such as getTicketAttachment, getStepMedia or getTaskMedia, so the distinction has to be inferred from the 'step answer' wording.

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

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

Gives explicit when-to-use guidance (share the URL with the user, or fetch it yourself when the user asks you to read or analyze the file) and an explicit when-not case: a metadata-plus-URL result is the intended answer, not an error, and must not be retried. It also points to the upstream tools that produce a valid resourceId, leaving no routing ambiguity for the common case.

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

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

Annotations only declare readOnlyHint=true; the description goes well beyond that by explaining the semantics of the two independent flags (active vs published), how pending aggregates new+needsReview, and that screeningSetUp=false is returned for betas without a form. With no output schema present, this return-shape disclosure carries real behavioral weight.

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

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

The first sentence front-loads the purpose and the detail sentences each convey distinct facts (flag independence, pending bundling, screeningSetUp=false). It is slightly dense but no sentence is pure filler; the final sentence is the closest to redundant with the earlier 'returns whether a screening form is set up'.

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 definition supplies the return contents, the meaning of each flag, the caveat about pending, and the empty-state behavior. There is nothing material an agent would need before invoking it.

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

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

There is only one parameter and schema coverage is 100%; the schema already tells the agent to get valid IDs from listProducts. The description adds no additional meaning about productId, so the baseline 3 for a fully documented schema 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: a summary of a beta's applicant screening pipeline. It then enumerates exactly what the summary contains (form-setup flag, counts by stage, auto-suggestion rule count), which lets an agent distinguish it from listApplicants (individual records) and getScreeningSetup (form configuration) 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?

Defines what an applicant is (filled out public screening form, no sign-in, reviewed then invited) and clarifies the relationship to listApplicants, explicitly noting that pending is not a valid listApplicants status filter. It never states a clean when-to-use-this-vs-sibling rule (e.g. 'use this for aggregate counts, use listApplicants for per-applicant data'), but the surrounding context makes the selection 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?

Consistent with readOnlyHint=true and adds substantial context beyond it: what ready=false blocks, that optional=true means skippable, that availableDate withholds a task, that URLs in media resources are time-limited links for the human user, that HTML wrapping is normal, that staged media ids legitimately differ from live ones, and that non-running/paused states return the live list with no unpublishedTasks/synced key. These are exactly the non-obvious traits an agent would otherwise misread.

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 ready/optional/availableDate guidance and the media/HTML traps are each worth stating, but they are packed into one dense paragraph with no structure, and the staging-area/synced explanation is repeated almost verbatim from the schema. Front-loading is fine, but the length and repetition cost readability.

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 does much of the work: it names the tasks/unpublishedTasks/synced keys, explains liveVersionId on staged entries, and flags the media resource shape. It does not enumerate step or label fields despite promising them in the first sentence, so an agent still learns some of the response shape by inspection.

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

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

Schema coverage is 100%, so both parameters are already documented in detail, and much of the description's text about the unpublished list (liveVersionId, synced, deletion semantics) largely restates the schema description rather than adding new meaning. The behavior of the version flag under different beta states is the main added nuance, so this sits at the baseline rather than above 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?

The opening sentence gives a specific verb and resource: 'Get the task list for the current beta, including steps, labels, and sync metadata.' That clearly separates it from mutation siblings like commitTaskChanges and from media siblings it explicitly points to. It never contrasts itself with results/performance siblings (getTaskResults, getStepPerformanceSummary), so the differentiation is good but not complete.

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

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

It gives real routing guidance: pass a media resource id to getTaskMedia or getStepMedia rather than fetching the time-limited URL yourself, and treat commitTaskChanges' preview as the authoritative statement of pending changes. The published-vs-staged selection criteria live in the schema rather than the description, and it does not say when to call this versus updateTask/createStep.

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

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

Annotations only supply readOnlyHint, so the description carries the burden and does so thoroughly: it explains that invitationStatus reads 'accepted' for opt-in/imported testers, that completion percentages are computed over label-gated visible-task sets and are not cross-comparable, that tag categories are opaque ids resolved via labels.categoryName, that unanswered custom fields are simply absent, and that location is country-only.

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

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

Front-loaded with purpose and the sibling exclusion before field-level caveats, and every sentence carries non-obvious semantics. The single dense paragraph and the long compound final sentence about lastAnswerAt make it harder to scan than it needs to be.

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 document return shape, and it does — covering invitationStatus, completion denominators, tag/category structure, customFields entries and their absence semantics, location granularity, and lastAnswerAt. Nothing an agent needs to interpret the response is missing.

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

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

The single productId parameter is fully described in the schema (100% coverage, including where to obtain valid IDs from listProducts), and the description adds nothing about it. With the schema doing all parameter work, the baseline of 3 applies rather than a penalty.

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 ('Get the list') + resource ('testers') + scope ('ALREADY ATTACHED to the current beta'), plus an enumeration of the payload (invitation status, completion stats, segmentation labels). It explicitly draws the boundary against listPendingInvitations, so an agent can separate this from the nearest sibling without opening a schema.

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

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

Gives an explicit exclusion rule — invitees without an account are not returned, use listPendingInvitations instead — and points to listCustomFields when full field definitions are needed. It does not address other plausible alternatives in the sibling set (e.g. getTesterFunnelDetail, listApplicants), so routing guidance is clear 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 readOnlyHint already declaring the safety profile, the description goes well past the annotations: it explains absence semantics (startAt/endAt missing while unscheduled, optInLink present only in published/running/paused and not implying opt-in is disabled, customInvitationEmail absent when never configured), link lifetime behavior (agreementUrl is time-limited and differs on every call while hasAgreement is the stable fact; url/testersUrl/etc. never expire and are sign-in gated), and visibility rules (description/objectives are manager-facing and hidden from testers). These are exactly the non-obvious traits an agent cannot infer from structured fields.

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

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

Purpose and siblings are front-loaded in the first two sentences, and nearly every subsequent clause disambiguates a specific returned field, so the length is largely earned. The downside is that it is one undifferentiated paragraph of dense clauses with no grouping or line breaks, which makes the field-semantics section harder to scan than it needs to be.

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 carries the full burden of explaining return values, and it does so comprehensively: the six-value state enum with meaning per value, the paused/state interaction, the opt-in link conditions, ticket-code prefix, invitation email template, and signed vs. permanent URLs. Nothing an agent needs in order to interpret the response correctly appears to be missing.

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

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

Schema description coverage is 100% and the single parameter productId is documented there, including the pointer to listProducts. The description body never mentions productId or adds any format or constraint detail beyond the schema, so this rests at the baseline for a fully covered 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?

Opens with a specific verb and resource ('Get the setup and configuration of this beta project') and then enumerates exactly which fields come back (name, description, objectives, lifecycle state, schedule, requirements). It explicitly carves out the adjacent territory by naming getBetaTasks for task content, so an agent can distinguish it from the most easily confused sibling without opening a schema.

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

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

It gives an explicit routing rule ('Use getBetaTasks for what the testers are asked to do') and the input schema directs the agent to listProducts for valid IDs. It does not address the other plausible neighbors (getBetaTesters, getApplicantsOverview, getScreeningSetup) or state any precondition for calling this tool, so the guidance is clear but not exhaustive across a very large sibling set.

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?

Consistent with readOnlyHint=true. The description adds substantial context the annotation cannot carry: the semantics of active/published (both must be true to accept applications), that questionIds are what rule conditions reference, the configured: false return case, and that ready: false blocks publishing and indicates a validation failure. It stops short of describing pagination or the exact shape of the returned rules, but the behavioral picture is 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?

Purpose and return contents are front-loaded before the workflow guidance. Dense but largely purposeful; the closing instruction about how to phrase the ready flag for users is agent-behavior guidance that adds length without adding tool semantics.

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, yet the description defines the return shape in words (configured flag, source fields, questions with ready state, rules) and explains the validation gating. For a single-parameter read tool this leaves nothing an agent needs missing.

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

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

Only one parameter (productId) at 100% schema coverage, and the schema already points to listProducts for valid IDs. The description adds no additional meaning about productId, so the baseline 3 applies even though the single-parameter surface makes the gap minor.

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 ('Get this beta project's applicant screening configuration') and then enumerates exactly what is returned: source flags and public link, thank-you copy, form questions with questionIds, and auto-review rules. That level of detail separates it cleanly from siblings like configureScreening, addScreeningQuestion, and publishScreeningForm.

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

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

Gives explicit routing: use configureScreening when screening was never set up (signalled by configured: false), author questions with addScreeningQuestion while the form is not live, then publishScreeningForm, and note that a LIVE form can only be edited from the Stomio dashboard. It names alternatives and the exact conditions that select them.

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

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

Annotations only declare readOnlyHint, so the description carries the real burden and does: it distinguishes inline image content from metadata-plus-URL fallbacks, notes URL time-limiting and per-call variation, and preempts the main failure mode by declaring that a metadata-plus-URL result is the intended answer, not an error.

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

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

Front-loads the action and the id source, then the two result shapes, then the anti-retry warning. Dense but nearly every clause earns its place; the final sentence about stable identity could have been folded into the preceding clause.

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

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

No output schema exists, and the description fully compensates by describing both possible return shapes and how to use them. For a two-parameter read tool, an agent has everything needed to call it and interpret the response.

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

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

Schema coverage is 100%, so both parameters are already documented. The description still adds meaning beyond the schema: that resourceId is the step's resource.id from getBetaTasks and is the stable identity while download URLs are not, which disambiguates which value to persist.

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 the media a manager attached to a step') and pins the scope with 'using the id of the step's resource as getBetaTasks returns it (published or unpublished)'. An agent can tell this apart from the task-media siblings without opening either schema.

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

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

Gives concrete when-to guidance on the returned URL ('share it with the user, or fetch it yourself when the user asks you to read or analyze the file') and an explicit prohibition ('do not retry it'), plus where the required id comes from (getBetaTasks). Little is left to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description goes further by explaining that answersPercentage uses a per-step denominator of testers who could see the step, which can vary between steps. It also discloses that bugTickets counts only OPEN tickets and is beta-projects-only and otherwise absent, which is exactly the kind of conditional behavior an agent cannot derive from annotations. It stops short of describing ordering, pagination, or response shape.

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 with the core purpose front-loaded, followed by the metric caveats. Dense but every sentence carries information an agent needs; minor cost is that the output-field caveats precede any statement of when to call the 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?

With no output schema, the description correctly takes on the burden of explaining key return fields — answersPercentage denominator, bugTickets scope and absence, and taskId grouping. For a single-parameter read-only summary tool this is close to complete, though the remaining response fields (raw response counts per answer option) are only gestured at.

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

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

Schema coverage is 100% and the single productId parameter is fully documented in the schema, including where to get valid IDs, so the baseline is 3. The description adds no further semantics for productId; its mention of taskId refers to a returned grouping field rather than an input, which is useful output context but not parameter guidance.

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: 'Summarize response counts and percentages for each step,' and adds the distinguishing focus 'highlighting bug-heavy prompts.' It does not explicitly contrast itself with nearby siblings such as getStepResults or getTaskPerformanceSummary, which report on different granularity, so an agent must infer the boundary from the name and text.

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 or when-not-to-use guidance and no mention of alternatives like getStepResults or getTaskPerformanceSummary. The only implicit cue is that the output is a per-step summary, leaving the agent to guess when this is preferable to a detailed results call.

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

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

Beyond the readOnlyHint annotation, the description explains missing answers for triggered-email steps, the special meaning of answers for instructions steps, seeded choice/rate counts with zero values, the other:true free-typed marker, and validation behavior for invalid filters. This gives an agent substantial behavioral context about what to expect and what errors mean.

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

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

The purpose is front-loaded in the first sentence, and the remaining sentences each cover a distinct return-shape or filtering behavior. It is dense and could use sentence breaks, 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?

With no output schema, the description carries the burden of explaining return values, and it does so for answers, triggeredEmails, choice/rate option counts, and instructions acknowledgments. It does not fully document every possible per-step analytics field, but it is complete enough for an agent to call the tool and interpret the main response shapes.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description adds filter behavior that the schema does not: an invalid tagId or testerUserId filter is rejected with an error rather than silently ignored, which changes how an agent should treat bad filter values.

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

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

The description opens with a specific verb and resource: 'Inspect an individual step to review grouped answers and other per-step analytics.' It clearly distinguishes this drill-down from getTaskResults and getStepPerformanceSummary by naming both siblings.

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

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

It explicitly routes skip-count questions to getStepPerformanceSummary and explains that getTaskResults reports only counts of instructions acknowledgments. The usage context is clear, though it does not enumerate every situation where a caller should choose this tool over getTaskResults.

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

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

Goes well beyond the readOnlyHint annotation: it explains what is returned inline (images as viewable content), what degrades to metadata plus a time-limited URL, that such a result is success rather than an error, and that URLs are unstable across calls while resourceId is the stable identity. This is exactly the behavioral context an agent needs to avoid misinterpreting results.

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

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

Front-loads the purpose and then layers the return-behavior rules; every sentence carries information, including the retry warning that prevents a common failure loop. It is dense and somewhat long, 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?

With no output schema and a read-only tool, the description fully covers what comes back in each case and how to interpret it, plus the stability caveat on the URL. Nothing an agent needs in order to call it and handle the result 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 already high, and the description adds provenance meaning for resourceId ('the id of the task's resource as getBetaTasks returns it') that helps the agent map it to the correct field. It does not add format or constraint detail beyond that, so it sits just above baseline.

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

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

States a specific verb and resource ('Fetch the media a manager attached to a task') and scopes it to testers following instructions. It names the source tool for the identifier (getBetaTasks) and is clearly distinguishable from siblings like getStepMedia, setTaskMedia, and removeTaskMedia.

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 directs the agent to get the resource id from getBetaTasks (published or unpublished) and describes the two usage branches: share the download URL with the user, or fetch it yourself when asked to read/analyze. It also gives a negative instruction — do not retry when a metadata-plus-URL result comes back.

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

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

Annotations supply only readOnlyHint, and the description does the heavy lifting: it defines the 14-day drop-off window precisely, discloses that denominators vary per task due to label-gated visibility, and explains that stepsCount excludes triggered-email steps. It also explains omission behavior (no-step and email-only tasks excluded) and that instructions-only tasks are still listed, which is exactly the kind of subtle behavior an agent could not infer.

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

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

Dense but almost every clause carries real semantic weight; the purpose is front-loaded. It is a single long paragraph where the denominator, drop-off, stepsCount, and omission rules would be easier to scan as separate sentences or a short list.

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 carries the return-value burden, and it defines testersCompleted, testersDropped, stepsCount, and completion semantics thoroughly. For a read-only summary tool with two simple inputs, nothing essential an agent needs to interpret or call it is missing.

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

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

Schema description coverage is 100%, so both productId and onlyCompletion are already documented in the schema with their effects. The description adds no additional parameter-level meaning — its detail is about returned fields, not inputs. 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 ('Get completion, drop-off, and ticket counts for every task in the beta') and implicitly scopes it against getBetaTasks and getStepPerformanceSummary by noting the list can be shorter and that counts are per task, not per step.

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

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

Gives clear context: use it for a per-task view of completion/drop-off/tickets, and explains why this list can be shorter than getBetaTasks ('That difference is not missing data'), which heads off a common misuse. It also points at the faster path via onlyCompletion. It does not explicitly state exclusions or name every alternative (e.g., getTaskResults), so it falls short of a 5.

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

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

The description adds substantial behavior beyond the readOnlyHint annotation: skipped testers are counted but not listed, choice/rate options are seeded with every offered option, other:true marks free-typed answers, completion:0 can mean no tester could see the task, file URLs are time-limited and unstable, and invalid tagId/testerUserId filters are rejected rather than ignored.

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-loads the purpose and then explains result-reading semantics in a single long paragraph. Most clauses earn their place because there is no output schema, though the semicolon-heavy structure is less scannable than it could be.

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

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

Given the lack of an output schema and the complexity of task result semantics, the description thoroughly covers skipped counts, per-step answer shapes, completion edge cases, time-limited file URLs, tester drop definitions, instruction-step exceptions, and filter validation. It is complete enough for an agent to call and interpret 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 coverage is 100%, so the schema already documents all four parameters, including tagId and testerUserId as optional filters. The description adds only a narrow validation note that invalid tagId/testerUserId filters are rejected with an error; it does not otherwise deepen parameter meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Get detailed results for a specific task, including step-level answers and ticket counts.' It also references sibling tools such as getTaskPerformanceSummary, getStepResults, and getAnswerAttachment, helping an agent distinguish this task-level results tool from related reporting 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?

It gives clear contextual routing: use getStepResults on an instruction step to see acknowledgments, and use getAnswerAttachment with a stable answer resource id for file attachments. It does not explicitly state when to choose this over getTaskPerformanceSummary versus when to use both, but the use 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?

Goes well beyond the readOnlyHint annotation by explaining which keys are omitted under which conditions, when engagementRate is null, and how the top-5 leaderboards are ranked and truncated. It stops short of defining what engagementRate actually measures or what the count fields are.

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

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

The purpose sentence is front-loaded and the return-value notes follow in a logical order (summary keys, then engagementRate, then leaderboards). The middle sentence about the NDA milestone is dense and takes effort to parse, but every clause conveys real conditional behavior.

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

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

With no output schema, the description properly carries the return-shape burden and documents key omission and null rules that would otherwise be surprising. It is incomplete on engagementRate's definition and on what funnel count fields exist, leaving the agent to discover the full key set.

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?

A single productId parameter with 100% schema coverage that already points to listProducts for valid IDs. The description adds no further meaning about the parameter, so the baseline 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 plus the exact contents returned: funnel counts, engagement rate, and top-tester leaderboards in one response. It is distinguishable from getTesterFunnelDetail only by implication ('in a single response', leaderboards), and never names the sibling.

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 is only implied — an aggregated summary for a beta project — with no explicit when-to-use or when-not-to-use guidance. The sibling getTesterFunnelDetail is the obvious alternative for per-tester breakdowns, but the description never routes the agent to it.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that timestamps accompany each milestone, which is real behavioral value about the payload shape, but it says nothing about volume, pagination, or whether results are per-tester rows or aggregates for the whole product.

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 the verb first and the milestone examples plus timestamp note packed in. No filler or redundant restatement of the name.

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

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

For a one-parameter read-only list tool with full schema coverage and no output schema, the description is minimally adequate. It leaves unresolved the key ambiguity of scope (all testers in the product vs. a single tester) and its relationship to the funnel dashboard sibling.

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

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

Schema coverage is 100% for the single parameter, and the schema itself tells the agent to source productId from listProducts. The description adds no scoping detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb ('List') and resource ('tester milestone') and enumerates the milestone types (invites, NDA, completions) plus the fact that timestamps are included. It does not distinguish itself from the very close sibling getTesterFunnelDashboard, so an agent cannot tell the two apart from the text 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?

There is no when-to-use guidance, no statement of when this is preferable to getTesterFunnelDashboard or getApplicantsOverview, and no prerequisites beyond the schema's note about productId. The only implicit guidance is 'list milestones', which the name already conveys.

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

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

Goes well beyond readOnlyHint=true: it discloses that images come back as viewable image content, that videos/files/oversized/unsupported images return metadata plus a time-limited download URL, and that this is the intended answer rather than an error. The explicit 'do not retry it' and the note that URLs change every call while resourceId is stable are exactly the behavioral facts an agent needs and cannot get from annotations.

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

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

Front-loads what the tool does, then the input provenance, then the return-shape contract. Every sentence carries non-redundant operational information (result shape, non-error status, retry prohibition, URL volatility); 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?

With no output schema, the description carries the full burden of explaining return values and does so by enumerating the two result shapes and clarifying which is not an error. For a two-parameter read tool, nothing an agent needs in order to call it or interpret its result is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the provenance of resourceId (attachment.resourceId on a message) and the fact that it is the stable identity while download URLs rotate. productId is left to the schema, which already points at listProducts.

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 one attachment from a ticket conversation') and scopes it to ticket attachments as opposed to answer attachments, so it is distinguishable from siblings like getAnswerAttachment. It also tells the agent exactly where the resourceId comes from, so the tool's role in the workflow 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?

Gives explicit preconditions ('using a resourceId taken from ... getTicketDetails or getTicketMessagesBatch') and clear post-fetch guidance (share the URL with the user, or fetch it yourself if asked to analyze the file). It does not name a sibling alternative for non-ticket attachments, so it stops short of full when/when-not routing.

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

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

Annotations only declare readOnlyHint, so the description carries real behavioral weight and does so: truncation is detectable via messagesReturned vs totalMessages, system entries are excluded and not counted in totalMessages, and tag groups are unnamed internal ids. The attachment semantics are unusually strong — url is a time-limited per-call link while resourceId is the stable identity, and ticketDetails.url is the permanent human-facing link.

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 truncation guidance is correctly front-loaded and nearly every clause carries substantive information, but the whole definition is a single unbroken block that runs well past what a two-parameter tool needs, and the senderRole explanation is a lengthy detour buried mid-paragraph.

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 explain the return shape, and it does so thoroughly: message envelope, senderRole taxonomy, attachment object shape, and the two distinct URL types. Given the tool's complexity as a combined metadata-plus-messages read, nothing an agent needs to interpret the response is missing.

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

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

Schema coverage is 100% for both required parameters, so ticketId and productId are already fully documented in the schema, including where to source the ids. The description adds no syntax, format, or edge-case guidance for either parameter, which is the expected baseline 3 when the schema does the work.

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 ('Get ticket metadata plus the newest conversation messages') and immediately scopes it as a 'most recent window' rather than full history. The sibling it could be confused with, getTicketMessagesBatch, is named and distinguished in the same sentence, so an agent can route without opening either schema.

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

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

It names two alternatives with their selecting conditions: getTicketMessagesBatch when full histories are needed, and getTicketAttachment when an image attachment must be viewed over MCP. It stops short of a full when-not-to-use statement (e.g., no guidance on when listTickets is the better starting point), which keeps it just below the top score.

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

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

Beyond readOnlyHint=true, it discloses the 25-ID processing limit, ignoredTicketIds behavior, exclusion of system entries, and the correct interpretation of an empty messages array. It also documents senderRole values, attachment structure, time-limited and changing URLs, and resourceId as the stable attachment identity.

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

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

The purpose, batch limit, and key sibling distinction are front-loaded, and each sentence supplies distinct operational or return-value information. It is nevertheless a long, dense single paragraph with several semicolon-heavy sentences, so bullets or shorter sentences would improve scanability.

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

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

With no output schema, the description compensates unusually well by documenting messages, ignoredTicketIds, senderRole, attachment fields, URL volatility, and empty-result semantics. Together with the complete input schema and read-only annotation, it provides the context needed to select, invoke, and interpret 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 coverage is already 100%, including the productId source and the ticketIds UUID and uniqueness constraints. The description adds useful operational context about batching and explains that excess IDs appear unprocessed in ignoredTicketIds, though it adds little further information about productId.

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

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

The description uses a specific verb and resource—fetching conversations for multiple tickets—and clarifies that it returns full conversational history. It explicitly distinguishes the tool from getTicketDetails, which only returns a window of the newest messages.

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

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

It explains when to prefer the batch tool: retrieving conversations for multiple tickets, up to 25, to reduce tool calls. It also guides selection between getTicketDetails for windowed history and getTicketAttachment for viewing an image attachment by resourceId.

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

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

Beyond readOnlyHint=false and destructiveHint=true, it discloses that the first call sends nothing, the executing call sends email, tokens are single-use and short-lived, and failures can be partial per applicant. The undeliverable case is especially transparent: the invitation persists without email, pinging will not help, and cancellation followed by reinvitation is needed.

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

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

The purpose and confirmation workflow are front-loaded, followed logically by prerequisites, failure behavior, and edge-case handling. The single dense paragraph and lengthy final sentence reduce scanability, and a few details duplicate the schema, but nearly all of the content is operationally useful.

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

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

For a consequential mutation with no output schema, it supplies the dry-run/execute protocol, approval requirement, eligibility and project-state preconditions, token lifecycle, partial-failure semantics, and response-field interpretation for undeliverable mail. Explicitly naming cancelInvitations for the final remediation would be a small improvement, but the essential invocation context is present.

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

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

Although schema coverage is 100%, the description adds operational constraints not captured there: productId must identify a published, running, or paused project, the second call must reuse the same arguments, and match ids can succeed or fail independently. Some shortlist and token details merely repeat the schema, so the added parameter value is not quite maximal.

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 specifies the action, population, outcome, and side effect: shortlisted applicants are invited to become beta testers and receive invitation emails. This applicant-specific scope, reinforced by the reviewApplicants prerequisite, distinguishes it from inviteTesters and the list/review siblings.

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

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

It explicitly requires a preview call, user review and approval, and a second call with identical arguments plus the token. It also states when invitations are refused based on applicant and project status, directs the agent to reviewApplicants first, and explains how to handle undeliverable addresses.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=true; the description adds the full behavioral picture: two-step preview/confirm gating, single-use short-lived tokens bound to resolved people and beta lifecycle state, no emails in DRAFT, refusal on finished/archived betas, server-side dedupe returning 'alreadyTester'/'invited' without re-emailing, undeliverable handling, and custom template usage. This is far more than the annotations convey.

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

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

The two-step procedure is front-loaded and nearly every clause carries load-bearing detail (token binding, dedupe outcomes, DRAFT suppression). It is dense and long, with several long run-on sentences and parentheticals that could be split for readability, but little is genuinely redundant.

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

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

For a 4-parameter mutation with no output schema, the description covers preconditions, the confirmation handshake, per-person result states (alreadyTester, invited, emailDelivery 'undeliverable'), and downstream follow-ups (pingTesters, cancelInvitations, listPendingInvitations). 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 already 100%, but the description adds meaning the schema does not: userIds and invitees 'combine freely' with at least one required (a union constraint not expressible in the schema), why userIds exist (tester emails are never exposed), and how confirmationToken interacts with identical arguments on the second call.

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

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

States a specific verb and resource ('Invites people to join this beta project as testers') and distinguishes itself from nearby siblings by naming inviteApplicants-adjacent tools (pingTesters, cancelInvitations, listOrganizationTesters). An agent can tell exactly which operation this performs 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 prescribes the call sequence (call without confirmationToken first, show preview, get user approval, then re-call with the token) and routes agents to alternatives by condition: use userIds for existing workspace testers from listOrganizationTesters, pingTesters to re-send pending invitations, cancelInvitations for undeliverable ones. It also states when the tool refuses (finished/archived) and when emails are suppressed (DRAFT state).

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

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

Annotations declare destructive=true and readOnly=false, and the description goes well beyond them: it discloses that testers with project-status emails enabled get notified, that the first call is a pure preview with no state change, and that tokens are single-use and expire in minutes.

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

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

Front-loaded with the action and its preconditions, then the two-step flow. Every sentence carries information, though the token mechanics are restated in both the description and the confirmationToken schema entry, adding mild redundancy.

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

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

For a destructive mutation with no output schema, the description covers the state precondition, side effects (tester notifications), no-op behavior, and the full confirmation workflow — everything an agent needs to call it safely.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by explaining that confirmationToken is obtained from the first call and must be sent with the SAME arguments, which the schema alone only partially conveys.

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 (start a PUBLISHED/scheduled beta project immediately) with scope clarified as overriding the start date, which cleanly separates it from siblings like publishBeta, pauseBeta, and resumeBeta.

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

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

Explicit preconditions and alternatives: only published projects can be launched, a draft requires publishBeta first, and calling it on an already-running beta is a no-op. The two-step confirmation protocol and the instruction to only re-call after explicit user approval are spelled out.

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

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

Goes well past readOnlyHint=true by disclosing non-obvious data quirks: recipientsCount includes courtesy-copy managers, view tracking exists only for testers so open rates must use testerRecipientsCount, recipients drop out when removed from the beta, and attachmentUrl changes every call while hasAttachment is stable. It also flags that the hand-picked-vs-all-tester distinction is unrecoverable and must not be guessed.

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 purpose and generally dense with earning content, but it runs long and repeats the courtesy-copy exclusion twice ('recipientsCount includes managers...' and 'Managers who received a courtesy copy are not in it'). A tighter ordering around recipient-list caveats would read better.

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

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

With no output schema, the description carries the full burden of return-value explanation and does so thoroughly: counts, testerRecipients shape, audienceTags semantics, date, and attachmentUrl versus hasAttachment. Given only two simple parameters and a read-only annotation, nothing an agent needs to call or interpret this correctly is missing.

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

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

Schema coverage is 100%, but the description still adds real meaning: recipientsSince not only enables testerRecipients but qualifies which announcements carry the list ('sent at or after it'), what fields appear in each entry (userId, name, username, viewed), and who is excluded from it. That is substantive semantics beyond the schema's one-line 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 and resource ('List the announcements already sent in this beta project') plus the fields returned (text, sender, audience tags, reach). The 'already sent' framing cleanly separates a read of past announcements from the sibling sendAnnouncement write tool, so an agent can pick between them without opening a schema.

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

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

Gives explicit conditional guidance for the optional parameter ('pass recipientsSince ... omit it for counts only') and warns against presenting an inferred sending method as fact. It never names an alternative sibling tool or states a when-not-to-call condition for the tool as a whole, which keeps it below a 5.

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

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

Beyond the readOnlyHint annotation, the description explains pipeline state semantics, the advisory nature of suggestedStatus versus the reviewed approvedStatus, when screeningAnswers is empty, and how pagination and counts/total can disagree. These are meaningful behavioral traits that an agent would not get from the annotations or schema alone.

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

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

The description is front-loaded with the core purpose and every sentence contributes useful semantics about statuses, output fields, pagination, or filtering. It is dense and slightly long for a list tool, but the length is largely justified by the absence of an output schema and the complexity of the applicant pipeline.

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 paginated list tool with no output schema, the description covers the key return semantics: matchId, suggestedStatus, approvedStatus, screeningAnswers emptiness, pagination behavior, and the intentional difference between counts and total. It also names the relevant overview alternative, leaving little an agent would need to infer before calling 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 already 100%, so the baseline is 3, but the description adds real meaning about the status enum by explaining which states are undecided, changeable manager decisions, or final. It also clarifies how offset is used when total exceeds the returned applicant count, though it does not add much beyond the schema for productId and limit.

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

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

The first sentence states a specific verb and resource: list people who applied to this beta project through its screening form, including their answers. It explicitly distinguishes this tool from getApplicantsOverview and ties the returned matchId to reviewApplicants and inviteApplicants, so an agent can identify its role among siblings.

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

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

It explicitly says to use getApplicantsOverview when only per-status counts are needed, which gives a clear alternative and implies this tool is for per-applicant detail. It also explains the pagination follow-up behavior and how the status filter interacts with total versus counts, giving practical invocation 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?

The readOnlyHint annotation already covers the safety profile, yet the description adds real domain behavior: labels are scoped to one beta project, they appear on testers and tasks, and they gate task visibility so completion percentages are per-tester. That visibility-gating rule is context an agent cannot get from annotations or schema, though return shape details (beyond categoryId) are absent.

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 is front-loaded in the first clause and each following sentence carries routing or domain information. The label-gating explanation is slightly tangential for a list call but earns its place by explaining why per-tester completion exists.

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

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

For a one-parameter read tool with no output schema, the description covers scope, the notable returned field (categoryId), the relationship to testers/tasks, and the correct sibling for creation. Only the full return structure and whether categories are always populated are left implicit.

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

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

Schema coverage is 100% and the single parameter already documents itself (productId, sourced from listProducts). The phrase "of this beta project" merely restates the schema's meaning and adds no format, constraint, or edge-case guidance beyond it, 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?

"List the labels of this beta project with their categoryId" gives a specific verb, resource, scope, and even the key returned field. It explicitly separates itself from ticket tags (listTicketTags) and names the creation sibling (createBetaLabels), so an agent can distinguish it from the surrounding list* tools 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?

The description tells the agent when to use a different tool: tickets use workspace tags via listTicketTags instead, and new labels are made with createBetaLabels. It does not mention updateBetaLabel/deleteBetaLabel as follow-ups for mutation, but the primary confusion risk (label vs. tag) is resolved.

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

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

Beyond readOnlyHint=true, it discloses useful result behavior: managerRole has three named values, the role is workspace-level, and name may be null with username as the addressing fallback. It does not describe pagination, ordering, or the overall return shape, but the disclosed quirks are substantive for this simple read 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?

The description is compact and front-loaded with the operation and scope, followed by two important result caveats and the scoped alternative. Every clause contributes actionable selection, interpretation, or invocation information without repetition.

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

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

For a single-parameter read-only list tool, the combined definition covers project scope, how to obtain the required ID, read-only safety, key result fields and their interpretation, nullable-name handling, and the workspace-wide alternative. Although there is no output schema, the description supplies the most important result semantics needed to select and use 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%, and productId is already documented as the beta project ID with valid IDs available from listProducts. The description's reference to "this beta project" adds no meaningful parameter detail beyond that schema, so the high-coverage baseline applies.

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

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

The description uses a specific verb and resource—listing managers assigned to a beta project—and clarifies that the returned role is workspace-level rather than per-beta. It also distinguishes this tool from the sibling listOrganizationUsers by workspace-wide scope.

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

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

It explicitly routes agents to listOrganizationUsers when they need the whole workspace rather than one beta's managers. The instruction to fall back to username when name is null also gives concrete guidance for using the results.

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

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

Annotations only supply readOnlyHint and a title, so the description carries the real burden and does: workspace-level configuration scope, that the list can legitimately be empty, that Person fields omit plain-email options, and that isForTesters=false fields have absent question/description. Those are non-obvious behavioral traits an agent could not infer from the schema or annotations.

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

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

Purpose is front-loaded in the first clause and each subsequent sentence carries distinct information (type enumeration, Person-option caveat, isForTesters semantics, empty-list meaning). The sentences are long and clause-dense, which slightly hurts scanability, 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?

There is no output schema, so the description must explain the return shape, and it does thoroughly: id, type with its full enum, choices for choice fields, Person member options with an exclusion, the isForTesters flag and its consequence, and the empty-list case. Nothing an agent needs to interpret the response is missing.

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

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

The tool takes zero parameters, so there is no parameter meaning for the description to add; this hits the baseline for a parameterless tool. The descriptive detail it does provide is about return values rather than inputs.

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

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

Opening clause gives a specific verb and resource ('List the workspace's custom profile fields') and immediately grounds it in the domain ('the questions testers answer about themselves during onboarding when a beta project has customFieldsRequired'). It also distinguishes itself from the related sibling by explaining that field ids match fieldId on getBetaTesters rows, so an agent can tell which tool answers which question.

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

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

Explicitly states the trigger for calling it ('use this to read what an answer means' after seeing customFields entries on getBetaTesters rows) and what an empty result implies. It lacks an explicit when-not or a named alternative to prefer in edge cases, which keeps it just short of a 5.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description goes further by defining what a flag actually signifies (a manager-only bookmark with no reason or author, indicating selection but not rationale) and by specifying newest-first ordering and the returned fields. It does not mention pagination, result caps, or behavior when no answers are flagged, which are the remaining gaps for a list tool 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?

Two sentences, front-loaded with the action and scope, then the flag semantics and sibling pointer. No filler and every clause carries information an agent would otherwise have to guess.

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

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

With no output schema, the description compensates by enumerating the returned fields and their ordering, and it explains the domain meaning of a flag. Only pagination/volume behavior is unaddressed, which is a minor omission for so simple a one-parameter read.

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

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

Schema coverage is 100% and the single parameter is documented in the schema itself, including where to obtain valid IDs (listProducts). The description only restates that the ID refers to a beta project, adding no syntax or filtering detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (list the answers managers flagged), scopes it to a beta project, and adds ordering (newest first) plus returned fields (answer text, author, task, step). This clearly distinguishes it from flagAnswer, the mutation sibling, and from generic result tools like getStepResults.

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

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

Explicitly routes the mutating counterpart to flagAnswer ('Set and clear flags with flagAnswer'), so an agent knows the division of labor between reading and writing flags. It does not compare against other list/result tools (getTaskResults, getStepResults, listApplicants), which leaves some inference for the retrieval case.

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

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

Goes well beyond the readOnlyHint annotation: it discloses the AI-enabled filtering rule, that rows show only AI-enabled memberships, and that out-of-range limit/offset are clamped rather than rejected, with the echoed values as the source of truth. It also flags that name may be null and username is the fallback, which is exactly the kind of post-call behavior an agent would otherwise get wrong.

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 scope are front-loaded, and every sentence carries substantive information about filtering, pagination, or result interpretation. It runs as one dense block with a long middle sentence about productIds that takes a second read, which keeps it just under top marks.

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

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

For a two-parameter read tool with no output schema, the description supplies everything needed to call it correctly and interpret the response: pagination mechanics, clamping, the meaning of total, the null-name fallback, and the workspace-versus-project id caveat. Nothing material is missing.

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

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

Schema coverage is 100% and both parameters are documented there, so the baseline is 3. The description adds real meaning beyond it: the clamping behavior for limit/offset, the need to read back echoed values, and the paging loop condition based on total versus returned count.

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 tester directory of this Stomio workspace') and immediately narrows scope: only testers belonging to at least one AI-enabled beta project, with a stated exclusion rule. An agent can distinguish this workspace-wide directory listing from the project-scoped tester tools without opening a schema.

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

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

Gives clear conditions for re-calling with a higher offset, and explains how returned productIds relate to project-scoped tools ('those ids read as not found... only ids also returned by listProducts are accessible'), which steers the agent away from misusing sibling tools on this output. It stops short of naming a specific alternative such as getBetaTesters vs listOrganizationUsers, leaving that comparison to inference.

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

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

Beyond the readOnlyHint annotation, the description discloses the returned member roles, project assignment semantics, the name-null/username fallback, pending invitation behavior, and privacy limitations around invited emails. It also explains an important access caveat: betaProjectIds can include projects the caller cannot access, which will read as not found in project-scoped tools.

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, starting with the core listing behavior and then covering fallback, access, and privacy caveats. Every sentence adds useful information, though the colon-heavy third sentence could be easier to scan if split into shorter statements.

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

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

With no output schema and no parameters, the description carries the full burden of explaining what is returned. It does so thoroughly: member roles, beta project ids and their access implications, pending invitation count/date behavior, and the missing invited-email detail are all covered.

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

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

This tool has zero parameters, so there is no parameter semantics to clarify. The baseline for a parameterless tool is 4, and the description appropriately spends its space on return-value meaning instead.

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

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

The description states a specific verb and resource: list members/managers of this Stomio workspace, including role, assigned AI-enabled beta projects, and pending invitation count. It is clear enough to distinguish this organization-wide roster from beta-scoped or tester-focused siblings.

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

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

Usage is implied by the workspace-level scope, but the description does not explicitly say when to use this instead of siblings like listBetaManagers or listPendingInvitations. It does provide useful context about cross-referencing listProducts for accessible project ids, but that is result-interpretation guidance rather than direct tool-selection guidance.

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

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

readOnlyHint already covers safety, and the description still adds substantial behavioral context: the exact returned fields, the conditional presence of email keyed to hasAccount, and the reason (tester email addresses are not exposed over this connection). The id-to-invitationId cross-reference with the funnel tools is non-obvious operational knowledge found nowhere in the annotations.

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

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

Front-loads what the tool lists, then the return shape, then the email caveat, then the routing guidance. The email/hasAccount sentence is long and slightly dense, but every clause carries real information for handling rows, so nothing is wasted.

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

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

There is no output schema, so the description carries the return-shape burden and does so precisely (id, name, invitedAt, lastPingAt, hasAccount, conditional email). For a single-parameter read tool, an agent needs nothing further to call and interpret it.

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

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

Only one parameter and schema coverage is 100%, so the schema already fully documents productId, including how to obtain valid IDs. The description reinforces that the query is scoped to a beta project but adds no format or constraint detail beyond the schema, making 3 the correct baseline.

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

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

States a specific verb and resource (list pending, not-yet-accepted tester invitations) scoped to the beta project, and explicitly separates itself from getBetaTesters. An agent can distinguish it from listOrganizationTesters or inviteTesters without opening a schema.

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

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

Gives an explicit use case (identify testers who haven't joined and may need a reminder), names the follow-on tools for acting on results (pingTesters, cancelInvitations), and states the exclusion that these invitees do not appear in getBetaTesters. When-to-use and when-not-to-use are both covered.

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

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

Goes well beyond the readOnlyHint annotation: it warns that the manager may have other beta projects not visible here, and defines each lifecycle state's tester-visible consequence ('draft' invisible to testers, 'published' testers cannot participate yet, 'paused' testers blocked). That is exactly the operational context annotations cannot carry.

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

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

Front-loaded with purpose and the 'call this first' routing cue before the detail. The state enumeration is long but each entry carries distinct meaning since there is no output schema; still, the list is the largest block and could be slightly tightened.

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

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

With no output schema, the description compensates by naming the returned fields and fully decoding the state enum. Combined with the visibility caveat and the downstream productId dependency, an agent has everything needed to call and interpret it.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing extra the description could add here. It correctly does not waste space restating an empty schema.

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

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

States a specific verb and resource ('List the beta projects you manage in this Stomio workspace') plus the exact fields returned (id, name, lifecycle state, url). This clearly separates it from sibling list tools such as listBetaManagers and listOrganizationUsers.

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 instructs 'Call this first to obtain the productId required by the other tools', giving both ordering and rationale. It also discloses the exclusion rule (only beta projects with AI features enabled), so the agent knows when results will be incomplete.

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

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

Annotations only declare readOnlyHint, but the description adds substantial behavior: assignable tags are manager-managed with stored counts, non-assignable entries are live-computed segments whose counts drift as testers work, they carry an extra slug field, and manageTesterTags will reject them. It also explains that overlapping ids in listTicketTags are one tag across two surfaces rather than a collision, which prevents a real misdiagnosis.

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 each clause carries non-obvious information (filter validity, assignable semantics, slug, cross-surface id overlap). The text is dense but justified; the final sentence about listTicketTags is valuable though slightly tangential to listing behavior.

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

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

There is no output schema, and the description compensates by describing entry contents (assignable flag, testersCount semantics, slug on smart tags) so the agent knows what comes back. For a single-parameter read tool with only readOnlyHint annotations, 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?

With a single required parameter at 100% schema coverage, the schema already documents productId fully, including where to obtain valid IDs. The description adds only indirect context by tying counts to 'this beta project's testers', so a baseline 3 is appropriate.

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

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

The opening clause gives a specific verb and resource ('List the workspace-level tester tags') and immediately scopes it by project ('how many of this beta project's testers carry each one'). It also distinguishes the two entry kinds (assignable vs computed smart tags) and names the related siblings getTaskResults, getStepResults, manageTesterTags, and listTicketTags, so an agent can place the tool precisely.

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

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

It states the practical downstream use ('their ids are the valid tagId filters for getTaskResults and getStepResults') and clarifies that manageTesterTags can only mutate assignable tags while rejecting non-assignable ones, which is strong when-to-use guidance. It also pre-empts confusion with listTicketTags. It stops short of an explicit 'call this before filtering' imperative, so a 4 rather than 5.

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

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

Annotations only declare readOnlyHint=true; the description adds substantial behavioral context beyond that: no cap and no paging, filters applied server-side and combined conjunctively (a ticket must match all), and precise semantics for derived fields such as messagesCount excluding automatic events and awaitingManagerReply ignoring manager-only notes. This is exactly the disclosure an agent needs for a non-paginated bulk read.

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 the dense field semantics are logically ordered (identity/link, enumeration scope, conversation state, then reply-waiting). It is long and repeats itself in places, explaining 'automatic events such as state or assignee change' twice and restating lastMessageFrom's value set, which slightly weakens the every-sentence-earns-its-place test.

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

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

With no output schema, the description carries the burden of explaining the returned shape and does so thoroughly: url, updatedAt, messagesCount, lastMessageAt/From/Internal, awaitingManagerReply, lastPublicMessageAt. An agent can interpret and act on the results without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond it by stating that optional filters narrow results server-side and combine with AND semantics, which the schema does not say. It does not add per-parameter detail on updatedSince or assigneeUserId beyond the schema, so it stops short of a 5.

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

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

Opens with a specific verb and resource ('Get list of tickets (feedback items) for the beta testing program') and clarifies the ticket domain (bugs, ideas, questions, chat). It also distinguishes itself from the thread-reading siblings getTicketDetails and getTicketMessagesBatch by naming them explicitly.

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

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

Gives explicit routing: use this to list/filter tickets, and 'Read the thread itself with getTicketDetails or getTicketMessagesBatch' for message content. It also warns to use awaitingManagerReply rather than lastMessageFrom when finding tickets awaiting a manager. It lacks guidance on when not to use it (e.g., single known ticket vs. getTicketDetails), but the alternative routing 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?

Read-only annotations are already provided, yet the description still adds substantial context beyond them: the tags are shared across all beta projects, never visible to testers, and are dashboard-managed configuration the MCP layer cannot mutate. It also explains the empty-result semantics, which is exactly the kind of behavior an agent cannot infer from a readOnlyHint.

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 statement and the manageTicketTags id linkage are front-loaded, and the sibling distinctions follow logically. The sentence about tag categories being configurable for tickets, testers, or both is dense but earns its place as the explanation for id overlap; the overall passage is longer than typical but has 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?

There is no output schema, so the description carries the return-value burden and does so: it identifies the tags as the ones visible in the ticket reads' "tags" field, emphasizes ids as the actionable output, and defines the empty-list case. For a one-parameter read tool this leaves nothing an agent needs unresolved.

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

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

With a single parameter and 100% schema description coverage, the schema already fully documents productId and how to obtain valid IDs. The description adds only an indirect clarification that the tag listing itself is workspace-wide despite the per-project productId, which is useful but marginal. 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 ("List the workspace-level tags that managers put on tickets") and immediately scopes it as workspace-level rather than per-beta. It explicitly disambiguates from two siblings, listTesterTags and listBetaLabels, so an agent can choose correctly without opening any schema.

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

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

It gives the practical trigger for calling the tool by explaining that the returned ids are what manageTicketTags accepts, and it rules out confusion with listTesterTags (same tag, both surfaces) and listBetaLabels (a separate concept). It also warns that MCP cannot create/rename tags, so an empty list means "none exist yet" rather than an error. What's missing is an explicit statement of when not to use it or whether it should be called before every manageTicketTags invocation.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the non-obvious behavioral facts: idempotent-per-conversation usage and that the returned rules are binding on all subsequent calls. It does not state what happens if called twice or whether a second call returns the same payload, which keeps it just short of 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, with the critical imperative front-loaded in caps so an agent scanning tool names cannot miss the ordering requirement. Zero redundant wording.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does so adequately by naming the categories of content returned. It stops short of describing the shape or size of the payload, which an agent might want before deciding how to consume it.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline is 4. No parameter detail is needed or given.

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

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

States a specific action (returns server conventions and workflow playbooks) with a concrete payload list (naming, vocabulary, concurrency handling). Because it is a bootstrap tool, the description immediately distinguishes it from every CRUD sibling in the list.

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

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

Explicit instruction: 'call this once per conversation, before any other tool,' plus the consequence that the returned rules are binding for every other call. There is no ambiguity about when to invoke it or how often.

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

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

Beyond readOnlyHint=false and destructiveHint=true, it discloses visibility to every tester, notifications, the thread announcement, permanent loss of privacy, eligibility restrictions, and token expiry. It also explains the non-obvious dry-run behavior: the first call changes nothing and returns a preview plus a confirmation token.

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?

Although relatively long, every sentence communicates a distinct consequence, restriction, or invocation requirement, and the core action is front-loaded. Emphasis on "ONE-WAY" and "TWO-STEP TOOL" appropriately highlights safety-critical information without wasting prose.

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

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

For an irreversible mutation without an output schema, the description covers the effects, exclusions, permanence, consent requirement, preview behavior, and token lifecycle. Together with the fully documented input schema and consistent annotations, it provides sufficient context for safe selection and invocation.

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

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

The schema already documents all three parameters, including identifier sources and the basic confirmation-token workflow. The description adds operational meaning by connecting the token to a user-visible preview, explicit approval, and expiration "after a few minutes," though it adds little new information about productId or ticketId.

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 clause identifies the exact resource and transition: "Makes an internal ticket public." It then clarifies the resulting visibility and interactions, distinguishing this operation from generic siblings such as updateTicket, updateTicketState, and replyToTicket.

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

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

It explicitly excludes chat tickets and tickets in App (SDK) projects, while the irreversibility warning helps the agent assess whether publication is appropriate. The preview-and-explicit-approval instructions precisely describe when and how to proceed with the executing call.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description carries everything else of value: no notification is sent, a label change marks the beta as having unpublished changes, duplicate adds/missing removals are no-ops, and edits are staged until commitTaskChanges (discardable via revertTaskChanges). It even flags a surprising response behavior: staged rows are returned even when live ids are passed, with liveVersionId linking back.

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 clause, and every sentence carries operational information rather than filler. It is dense and long, with the staging/id-echo material packed into the final sentences, so an agent must read to the end, but nothing is truly redundant.

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

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

For a non-destructive mutation tool with no output schema, the definition covers input sourcing, side effects, no-op semantics, staging lifecycle, response shape, and the terminal archived/finished restriction. Nothing an agent needs to invoke it safely 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 the decisive semantic that the label id parameters use manager-internal beta label ids rather than workspace ticket tags or tester tags, which the schema does not say. It also clarifies the no-op conditions for addLabelIds/removeLabelIds. It does not repeat the 50-item cap, which 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 pair and resource ('adds and/or removes per-beta labels on a single task') plus the return value, and explicitly separates itself from the similarly named label tools (listBetaLabels, createBetaLabels, listTicketTags, listTesterTags). An agent can route correctly without opening any sibling schema.

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

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

Names the prerequisite tools for obtaining ids ('Get assignable ids from listBetaLabels (create new labels with createBetaLabels)') and explicitly excludes the wrong namespaces (ticket tags, tester tags). It also states the conditions that change behavior: draft/scheduled projects apply immediately, running/paused projects stage the change, and finished/archived projects are read-only.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the visibility model ('manager-internal: the tester sees nothing and no notification is sent') and idempotency semantics ('adding a label the tester already has, or removing one they do not have, is a no-op'). It also states the return: the tester's resulting labels. That is exactly the behavioral context annotations cannot carry.

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

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

Three sentences, each carrying a distinct payload: what it does, where ids come from plus the disambiguation, and the behavior/visibility notes. The verb+resource lead is front-loaded and 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 mutation tool with no output schema, the description supplies the mutation target, id provenance, side-effect profile, idempotency, and the shape of the response. Nothing an agent needs to invoke it correctly 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?

Schema coverage is 100%, so the baseline would be 3; the description earns more by pinning down the correct source of label ids and by warning that these are not tester tags or ticket tags — a distinction the schema's generic 'from listBetaLabels' note only partly makes. It adds no detail on the 50-item cap or ordering, but the schema covers those.

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

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

The description states a specific verb and resource: 'Adds and/or removes per-beta labels on a single tester of this beta project.' The scope qualifier ('per-beta labels', 'single tester') and the explicit exclusion of workspace tester tags and ticket tags separate it cleanly from the many sibling label/tag 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?

It gives concrete prerequisites — assignable ids come from listBetaLabels, new labels come from createBetaLabels — and explicitly rules out the wrong id sources (listTesterTags, listTicketTags). What is missing is an explicit steer against the near-sibling manageTesterTags, which an agent could plausibly confuse with this tool.

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

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

Strong disclosure beyond annotations: cross-project workspace scope, an automatic side effect that mutates all private tickets and notifies their audiences, per-tag application without group rollback, and idempotent no-ops. However, it does not state permission requirements or which roles can call it, so it is not fully 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?

Front-loaded with the core action, then constraints and side effects in decreasing priority. Dense but nearly every clause carries operational value; the sibling-disambiguation sentence is long, though still informative.

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, but the description states it returns the tester's resulting tags. Scope, idempotency, partial-failure semantics, and side effects are all covered for a 4-parameter mutating tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: tag ids must come from listTesterTags and be assignable, and the userId must be the user id rather than a tester id. It does not restate the 50-item caps or explain interaction between addTagIds and removeTagIds.

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 ('Adds and/or removes workspace tester tags on a single tester') and names the exact siblings it is not: listBetaLabels and listTicketTags. An agent can distinguish it from manageTesterLabels/manageTicketTags without opening a schema.

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

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

Gives the source for ids (listTesterTags), the filter to apply (only entries with assignable=true, otherwise rejected), and no-op conditions for already-present/absent tags. It also states that re-running with the same ids is safe after a partial failure, which is exactly the recovery guidance an agent needs.

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

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

Beyond the annotations, the description discloses that ticket tags are manager-internal, never shown to testers, and send no notification. It also states that the tool returns the ticket's resulting tags and that adding an existing tag or removing a missing tag is a no-op.

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

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

The description is front-loaded with the core action and return value, then adds only relevant context about visibility, id sources, dashboard limitations, and idempotency. Every sentence contributes distinct operational guidance without repetition.

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

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

For a mutation tool with no output schema, the description is complete enough: it explains what changes, what is returned, who can see the result, where ids come from, what cannot be done through MCP, and how redundant operations behave. No critical agent decision is left unaddressed.

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?