Duvo MCP

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

The description discloses useful context: organization admin+ permission, area-folder-only constraint, and no-op behavior on re-acceptance. However, it directly contradicts the annotation 'idempotentHint: false' by asserting that re-accepting an already-active area is a no-op, which implies idempotent 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 three sentences with no filler. It front-loads the core purpose, then adds the key constraint, the alternative tool, and the no-op edge case. Every sentence carries useful information.

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

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

The description covers purpose, permissions, constraints, and an alternative, but the idempotency contradiction makes the behavioral model unreliable for an agent. Additionally, orgId is left undocumented in both the schema and the description, leaving a meaningful gap for a two-parameter 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 only 50%, with nodeId described but orgId not. The description adds meaning by clarifying that nodeId refers to a proposed area folder and that only area folders are valid, but it does not explain orgId beyond its parameter name, leaving part of the input semantics underspecified.

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 ('Accept') and resource ('proposed area folder'), clearly explaining the state transition from proposal to active structure. It also distinguishes itself from assignClarityLandscapeNodeTeam, so an agent can tell them apart.

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

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

The description explicitly states when to use this tool (accepting proposed area folders) and when not to ('proposed process becomes real through assignClarityLandscapeNodeTeam instead'). It also clarifies the no-op behavior for already-active areas, giving clear operational guidance.

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

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

Annotations already indicate a non-read-only, non-idempotent mutation. The description adds that the outcome is gaining process access, but it does not disclose details like token consumption, failure behavior, or authorization requirements. This is acceptable but not rich.

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

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

The description is a single efficient sentence that front-loads the action and states the outcome. There is no wasted wording or unnecessary repetition of the title.

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

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

For a simple tool with one required parameter and no output schema, the description provides the core idea but leaves parameter semantics and post-acceptance behavior unstated. It is minimally viable but not fully complete.

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

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

Schema description coverage is 0%, and the description never mentions the 'token' parameter directly. It only says 'invite link,' which gives vague context but does not explain that the token comes from the invite link, its format, or how to supply 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 description uses a specific verb ('Accept') plus a resource ('a clarity interview invite link') and an outcome ('gain process access'), making the tool's purpose clear. It does not explicitly differentiate from sibling tools like getClarityProcessJoinInfo or createClarityInviteLink, but the action is distinct enough.

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

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

The description implies when to use the tool: when a user has a clarity interview invite link and wants to accept it. However, it provides no explicit guidance about alternatives, prerequisites, or cases where this tool should not be used.

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

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

Annotations already indicate this is not read-only, and the description adds that the assignment is 'durable', clarifying persistence and mutation. It does not disclose whether the accepted suggestion is consumed, whether a previous assignment is overwritten, or any other side effects. Given the annotations, this is adequate but not rich.

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

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

The description is a single, tightly worded sentence with no filler, tautology, or repetition of the tool name. It front-loads the action and then gives the essential object and outcome, making it easy to scan.

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

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

For a simple two-parameter mutation, the description covers the core purpose and effect, and the annotations cover the read-only/destructive expectations. However, it does not explain how to obtain a valid nodeId or suggestionId, nor what happens after acceptance. An agent would likely need external knowledge or sibling tools to invoke 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 description coverage is 0%, and the description does not explain what nodeId or suggestionId refer to beyond their self-descriptive names. It does not clarify where these IDs come from or how they relate to the 'suggested team' mentioned in the description. The description fails to compensate for the complete lack of parameter documentation.

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 ('Accept'), identifies the exact resource ('pending Process Landscape team-assignment suggestion'), and states the resulting effect ('durably assign the suggested team'). It clearly differentiates this from sibling tools like dismissClarityTeamAssignmentSuggestion and assignClarityLandscapeNodeTeam by focusing on accepting an existing suggestion rather than dismissing or directly assigning.

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

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

The description implies the tool is for confirming an already-pending team assignment suggestion, which gives some contextual usage guidance. However, it does not explicitly state when to choose this tool over alternatives, nor does it mention related tools such as dismissClarityTeamAssignmentSuggestion or how pending suggestions are discovered. The usage condition is mostly 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 indicate a non-read-only, non-destructive, non-idempotent mutation. The description adds meaningful behavioral context by stating the acceptance completes the builder run and that the saved draft is not activated, preventing a likely misinterpretation that acceptance equals activation. No contradiction with annotations was found.

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

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

Two short sentences with no filler. The primary action and outcome are front-loaded, and the critical non-activation caveat is placed second without 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 three-parameter tool with fully documented schema properties, the description plus schema provides sufficient guidance for the agent to call it correctly. The one gap is the lack of explicit procedural context about when in the generation/review workflow acceptance should occur, though the description and parameter descriptions imply it well enough.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the important guidance on expected_started_at and stale review identities returning 409. The description itself adds no parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Accept') and resource ('reviewed generated configuration') and adds the outcome 'complete the builder run.' It also differentiates from related siblings like activateAutomationRevision by explicitly noting the saved draft is not activated, and from declineRevisionGeneration via the accept/decline contrast.

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 context is implied: use this after reviewing a generated configuration and wanting to complete the builder run. However, it does not explicitly name alternatives such as declineRevisionGeneration, cancelBuilderRun, or resumeBuilderRun, nor does it provide clear when-not-to-use guidance beyond the non-activation clarification.

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

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

Adds real behavioral context beyond the annotations: preconditions (no existing automation membership), immutability of revision bindings, and the re-add-succeeds-unchanged outcome, which is a useful edge case. It does not state error behavior, required permissions, or side effects beyond membership.

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 in the first clause, and every sentence carries substantive content (preconditions, immutability, idempotent-like outcome). However, the em-dash-heavy, run-on phrasing makes it denser than necessary and slightly harder to scan.

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

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

For a two-parameter mutation with annotations covering safety hints and no output schema, the description covers the important edge cases and preconditions. Remaining gaps (permission requirements, failure modes) are minor for a tool of this complexity.

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

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

Schema description coverage is 100% for the two UUID parameters, so the schema already carries the full parameter documentation. The description refers to agents and automations conceptually but adds no format, lookup, or constraint detail beyond the schema.

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

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

States a specific verb (add) and resource (agent to an automation) with scope qualifiers (team on the Automations workspace). It also distinguishes itself from revision-scoped siblings by explicitly stating 'membership is not versioned', contrasting with tools like setAutomationRevisionAgent.

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 preconditions: the agent must not already belong to another automation, and on revision-based teams it cannot be moved between automations. It does not name an explicit alternative tool (e.g., setAutomationRevisionAgent) for the revision case, so routing is inferred 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so mutation semantics are partly covered. The description adds genuinely non-obvious behavior: membership is not versioned, revisions bind immutably, and re-adding an existing member succeeds unchanged — context the annotations cannot convey.

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

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

Front-loaded with the core action, then the constraints. It is dense — several ideas packed into two long sentences — but each clause (non-versioned membership, immutability, re-add behavior) carries real information, so little is wasted.

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

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

For a two-parameter mutation with no output schema, the description covers the key calling constraints and edge cases (existing membership, revision-bound queues). It does not describe error/failure modes or required permissions, a minor gap given the annotation coverage.

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

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

Schema description coverage is 100% with only two UUID parameters (automation_id, case_queue_id), so the schema already carries the semantics. The description adds no format, source, or constraint detail for the individual parameters, so the documented 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 (add) and resource (queue to an automation) plus the constraining scope (team on the Automations workspace, versioned vs. revisioned). This lets an agent distinguish it from setAutomationRevisionQueue / removeAutomationQueue without opening a schema.

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

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

The description gives preconditions (queue must not already belong to another automation; on revision-based teams it cannot be moved between automations) but never names an alternative sibling tool or explicitly says when to prefer setAutomationRevisionQueue over this one. Usage is implied through constraints rather than routed.

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

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

Annotations already flag a non-read-only, non-idempotent, open-world mutation, but the description adds material side-effect detail beyond them: supplying an email grants the person access and dispatches an invitation email. This is exactly the kind of behavioral consequence the agent needs, though it omits team/role effects.

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

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

Two tightly written sentences with the core side-effect warning placed prominently. Every clause earns its place with no 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 7-parameter mutation tool with only 14% schema coverage and no output schema, the description covers the invite/access behavior but leaves role, teamId, and teamRole entirely unaddressed, so it is adequate but incomplete.

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 14%, so the description carries most of the burden. It explains the semantics of name and email well, but role, teamId, and teamRole are undocumented in both the schema and the description, leaving a meaningful gap.

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

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

The description states a specific verb+resource: adding a person to the process behind a landscape node. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like batchAddClarityLandscapeNodePeople or updateClarityLandscapeNodePerson.

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 conditional constraint: a name alone records a placeholder, while an email grants process access and sends an invite, so only pass an email the user asked to invite. It lacks explicit routing to sibling alternatives (e.g. the batch variant), but the usage condition is clear.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real context on top: the key-naming/collision scheme and, notably, that a template reinstall won't overwrite fields added here. That persistence guarantee is the kind of behavioral trait annotations cannot express.

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

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

Two sentences, front-loaded with the core action, then the naming and placement rules. No filler or redundancy; every clause carries information.

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

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

For a 13-parameter create tool with no output schema, the description omits which fields are required (automation_id, label, question, type) and how the returned field is identified. The rich schema compensates, but a create operation would benefit from a note on required inputs and the effect on the automation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description elaborates the key derivation (custom_ prefix, snake_case label, _2/_3 suffix on collision), which slightly amplifies the schema's 'derived from the label when left out', but leaves the other 12 parameters entirely to the schema.

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

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

The description states a specific verb and resource ('Add a Policy question to this automation') and clearly delimits the tool from siblings like updateConfigField, listConfigFields, and addConfigSection. An agent can identify exactly what this creates 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 implies the context (adding a new field to an existing automation) and states a placement rule, but never says when to prefer this over updateConfigField or how it relates to addConfigSection. No explicit alternatives or when-not-to-use guidance is given.

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

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

Annotations already mark this as a non-read-only, non-idempotent, non-destructive mutation. The description adds real value beyond them: the deterministic key derivation (lowercase-hyphen with -2/-3 suffixes when taken), the case-insensitive 409 refusal, and the guarantee that a module template reinstall leaves the section intact.

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

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

Three sentences, front-loaded with the core action and placement, then the key-generation and conflict rules. Dense but each sentence carries distinct information; 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 with no output schema and full param documentation, the description covers the key edge cases an agent needs: name collisions, generated key format, and persistence across template reinstall. It omits return shape and auth requirements, but those are minor given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description explains the name-to-key transformation and the conflict behavior, which the schema does not. The after_key fallback ('omitted, it goes last') is also clarified, adding meaning beyond the raw schema.

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

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

States a specific verb (add) and resource (empty section) scoped to the automation's Policy, with placement semantics. It is clearly distinguishable from addConfigField and renameConfigSection by resource, though it never names a sibling explicitly.

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

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

The description implies usage through the placement and key-conflict rules, but it never states when to choose this over addConfigField, renameConfigSection, or reorderConfigSections, nor any prerequisite conditions. Usage is inferable rather than guided.

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 already marking this as non-read-only and non-destructive, the description adds useful behavioral context: the tool resumes a paused run and is restricted to creators/team editors. It also explains that toolCallId comes from the dashboard transcript. No contradiction with annotations is present.

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

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

The description is a single, front-loaded sentence with no filler. It states the action, the governing context, the allowed actors, and the key parameter source in an economical way.

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?

While the description is clear about the tool's purpose and auth scope, it leaves two of three required parameters underspecified in a schema with zero descriptions. There is no output schema, so the description carries the full burden, but it does not explain what artifactId refers to or how the answers object should be populated.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only explains toolCallId's origin. artifactId and the structure/semantics of the answers object are left undefined, leaving an agent to guess what keys and values the answers object expects.

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: 'Answer a pending question the Duvo Pulse agent asked' and clearly identifies the follow-up effect: 'resume the paused run'. This is not a tautology and is specific enough to differentiate from generic tools like respondToHumanRequest or sendPulseDashboardMessage.

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

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

The description provides clear context on when to use the tool: only for pending Duvo Pulse agent questions on a paused run, and only for 'creator or team editors'. It also gives a concrete source for toolCallId. It stops short of explicitly naming alternatives or saying when not to use it, so it does not reach 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?

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=false, openWorld=false) by disclosing role requirements (Builder), HTTP-level refusal conditions (409/403), the safe retry behavior ('already_started' rather than starting twice), and that the actual mutations happen inside a user-mediated Ask Duvo conversation. This is the permission, side-effect and failure-mode context an agent needs before triggering a build.

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 purpose and the web-app analogue, then layers behavior, parameters, errors and the confirmation warning in a sensible order. Sentences are long and dense, especially the first, but every clause carries information an agent would otherwise have to guess.

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

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

For a mutation tool with no output schema and no annotation coverage of failure modes, the description supplies the conversational flow, the returned `url` handoff, the `already_started` status, authorization thresholds and error codes. 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%, so both UUID parameters are already documented; the description adds the operational constraint that `proposal_snapshot_id` must be the live proposal and that omitting it defaults to whichever is live, plus the consequence (409) when no live proposal exists. Marginal value over the schema, but real.

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 ('Approve the automation proposal of a Module automation being set up') and anchors it to the web-app equivalent ('the same as the setup's Approve and build'), which distinguishes it from siblings like generateAutomationProposal or buildClarityAutomation. The downstream effect (opens Ask Duvo conversation that proposes and applies changes, then finishes the setup) makes the action 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?

Explicitly instructs 'Confirm with the user before calling: approving starts the build' and tells the agent what to do with the returned conversation `url`. It also enumerates when the call will fail (409 when no live proposal, open Policy questions, or Ask Duvo unavailable; 403 below Builder) and when to pass or omit `proposal_snapshot_id`.

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 a behavioral detail beyond the annotations: labels are created if they don't already exist. While the annotations already indicate the tool is not read-only, this note clarifies a side effect but does not cover other aspects like error handling or idempotency.

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

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

The description is a single, concise sentence that immediately states the action and the key side effect. It is well-structured with no redundant or extraneous information, making it easy to parse.

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

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

The description covers the primary action and a notable side effect, but it omits details about the return value or any error conditions. Since no output schema is provided, the agent is left without knowledge of what the tool returns, which is a gap for a complete understanding.

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 describes queue_id and case_id, but the labels parameter lacks a description. The tool description does not compensate, offering no explanation of what 'labels' entails beyond its name. This leaves ambiguity for the labels structure, especially since it contains nested key-value pairs.

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

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

The description clearly states the action: 'Assign one or more labels to a case' and adds a specific side effect about creating missing labels. It distinctively describes the tool's function without ambiguity, and the name aligns well with the description.

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 does not provide explicit guidance on when to use this tool versus alternatives like unlinkCaseLabels or updateCase. It merely states what the tool does, leaving the agent to infer the appropriate context from the tool name and sibling list.

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

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

Annotations already declare the mutation/destructive/idempotent profile, so the added value here is the authorization requirement and the dual assign/unassign behavior, both of which go beyond structured fields. It stops short of explaining what the destructiveHint actually means (e.g., whether an existing assignee is replaced) or how failures surface.

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

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

Two short sentences with the core action and the null-unassign variant front-loaded; the permission caveat follows without padding. Every clause earns its place.

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

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

For a four-param mutation tool with full schema coverage and annotations supplying the safety profile, the description contributes the missing auth requirement and the assign/unassign duality. Return behavior and the effect on any prior assignee remain unstated, but no output schema exists to fill that gap.

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

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

Schema coverage is 100% and each parameter is already documented, including 'null to unassign' for user_id, so the description adds no syntax or format meaning beyond the schema. Baseline 3 applies when the schema carries the full parameter burden.

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

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

The description names a specific verb (assign/unassign), its resource (extra-capture request), and its subject (a team member), so the action is unambiguous. It does not, however, distinguish itself from the near-identical sibling assignClarityLandscapeCaptureRequest, which an agent could easily confuse for the same operation.

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

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

It concisely explains the unassign case via `user_id: null` and states the permission gate 'Lead Builders and above', which is real usage context. It offers no explicit when-to-use versus the Landscape or Team assignment siblings, leaving the routing decision 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?

Adds meaningful context beyond the annotations: the admin+ permission requirement, the side effect that a proposal is accepted and a real process is created, and that a move also relocates the process's captures and brief. That discloses scope of mutation well, though it does not address reversibility or failure modes beyond what the schema states.

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

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

Two dense sentences, front-loaded with the action, then the permission gate, then the two behavioral branches. 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?

For a destructive, idempotent mutation with no output schema, the definition covers permissions, side effects, and outcome branching, which is what an agent needs before calling it. Minor omissions (no note on reversibility or what a successful response yields) keep it short of a 5.

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

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

Schema description coverage is 75% and the descriptions already cover intent semantics (the fail-if-already-accepted behavior) and teamId's null rejection. The description implies the 'accept-proposal' path but never names parameters or adds syntax beyond the schema, so it sits at the baseline.

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

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

States a specific verb+resource: setting the owning team of a process in the process landscape, and spells out the two distinct outcomes (accepting a proposal vs. moving an existing process). This is clear and concrete, but no sibling tool is named (e.g., setClarityLandscapeNodePlacement, acceptClarityLandscapeNode), so differentiation is implied rather than explicit.

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

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

Provides a real precondition (organization admin+) and explains that behavior branches on whether the node is still a proposed process or an already-accepted one, which tells an agent when each mode applies. It never explicitly routes the agent away from alternatives or states when not to use this tool.

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

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

Annotations indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description must explain side effects. It does not disclose whether assigning labels replaces existing process labels or appends to them, whether labels are created inline or referenced by ID, or what the response looks like. The word 'assign' only signals mutation without adding meaningful behavioral detail.

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

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

The description is a single sentence with no filler, making it easy to scan and front-loaded with the main action. It is concise, though it is too sparse to be considered a fully developed 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?

For a three-parameter mutation tool with no output schema and no parameter descriptions, one sentence is not enough. It does not state whether labels and labelIds are alternatives, whether the operation replaces or adds tags, or what happens when only id is supplied, leaving agents unable to invoke it confidently.

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 has 0% description coverage and the description adds no parameter-level meaning. It leaves the crucial labels-vs-labelIds distinction ambiguous, does not mention colorHue, and does not clarify that id is required while labels and labelIds are optional 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 uses a specific verb ('assign') and identifies both the object ('process tags'/'labels') and the target ('a process'), so the core operation is clear. It does not explicitly distinguish itself from close siblings such as createClarityProcessLabel or assignClarityLandscapeNodeTeam, but it is not a tautology or misleading.

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

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

No guidance is given about when to use this tool instead of alternatives like assignCaseLabels, assignClarityExtraCaptureRequest, or unlinkClarityProcessLabels. The sentence merely restates the action and provides no conditions, exclusions, or selection criteria.

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 mark this non-read-only, open-world, non-idempotent with no destructive hint. The description goes well beyond that by disclosing the real-world side effect (this emails a real person), the consent requirement before invocation, and the admin-only authorization gate. That is material behavioral context the annotations alone do not convey.

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

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

Front-loaded with the purpose, then the parameter branching, then the safety caveats. Dense and mostly waste-free, though the two trailing caution sentences could be tightened slightly.

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 action tool with no output schema, the definition covers the identity of the resource, the parameter branches, the side effect, and the consent/authorization gates. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so all three params are already documented. The description restates the same invited_email and context semantics found in the schema, adding only the 'exact address the user gave you' caveat. Baseline 3 is appropriate since the schema carries the burden.

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

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

States a specific verb (assign) and resource (Policy interview), and clarifies what that means: a Clarity voice interview covering the automation's open Policy questions whose answers are written back onto them. An agent can distinguish this from sibling interview tools like sendClarityInterviewInvites or assignClarityLandscapeCaptureRequest.

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 branching guidance: pass invited_email to email someone vs. leave it out for an unassigned slot, plus the selection condition for context. Adds hard preconditions (only after the user says yes, only an address the user gave you, admins and above only), which is exactly the when/when-not info 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?

Annotations only declare it is a non-idempotent, non-destructive write. The description goes well beyond that: real email is sent, existing accounts get the role immediately while others get an invitation, team role is never lowered, SSO-required orgs return 403, and a pre-existing role triggers 409. This is unusually rich side-effect and failure-mode disclosure.

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 side effects then preconditions, and no sentence is filler. It is long and the email-provenance warning is stated twice (once in narrative, once echoed by the schema), which is the only real 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?

Complete for a tool with no output schema and partial annotation coverage: it explains the result (role granted now vs. invitation pending acceptance), the permission requirement, the 403/409 outcomes, and the confirmation obligation. An agent has everything needed 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 description coverage is 100%, so all three parameters are already documented in-schema, including the role_key-from-listProcessRoles and email-provenance rules. The description restates those same constraints rather than adding new syntax, format, or edge-case semantics, so the baseline 3 applies.

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

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

Specific verb+resource+scope: 'Put one person on an automation in one of its process roles,' which cleanly separates it from removeClarityProcessMember, listProcessRoles, and the broader inviteOrgMember sibling. The mechanics of what assigning means are spelled out in the same breath.

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: take role_key from listProcessRoles, managers-and-above permission gate, mandatory user confirmation before calling, and it routes to the People tab when the call is refused. It also states which email addresses are eligible versus which are off-limits.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the agent knows this is a non-read, non-idempotent mutation. The description adds the edit-access requirement and the effect of enabling the agent's tools on the dashboard, which is useful context. It does not disclose whether attaching is additive vs. replacing existing connections, but it is not misleading.

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?

One sentence, front-loaded with the action and target, and the parenthetical clarifications ('data sources', 'requires edit access') earn their place. It is efficient without being terse to the point of ambiguity.

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 2-param mutation with no output schema, the description covers the core action and the key prerequisite (edit access). It falls short of complete because it doesn't state whether the attachment replaces or appends to existing connections, and there is no mention of validation effects or error conditions. Still adequate for an agent to attempt the call 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 0%, but the parameter names are strongly self-descriptive: artifactId clearly refers to the dashboard and connection_id to the data source. The description maps 'connections (data sources)' to connection_id and 'dashboard' to artifactId, providing just enough disambiguation. Since param names carry most of the meaning, a 3 is appropriate.

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

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

The description states a specific verb ('Attach'), a resource ('connections/data sources'), and a target ('a Duvo Pulse dashboard'), and adds the agent-relevant outcome ('so the agent can use its tools'). It is clear enough to distinguish from siblings like detachPulseDashboardConnection, though it doesn't name that sibling explicitly.

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

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

The description implies the usage context: attaching an existing connection to a dashboard, and it parenthetically adds the prerequisite 'requires edit access'. However, it does not state when to prefer this over listPulseDashboardConnections or createConnection, nor give any exclusions or alternatives.

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

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

The description discloses a critical non-obvious behavior: attaching case-queue integrations alone leaves the slot pointing at no queue and will fail at runtime until queues are linked. It also recommends a verification step. While annotations already indicate this is a mutating operation (readOnlyHint=false), the description adds meaningful behavioral caveats beyond the structured annotations.

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

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

Three sentences, front-loaded with the core action, then the alternative tool, then the important workflow caveat. Every sentence earns its place; no fluff or repetition of schema details.

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 and lack of an output schema, the description is remarkably complete: it states the action, routes to the correct sibling for pinning, warns about a runtime failure mode, and tells the agent how to verify success. An agent has enough context to invoke this correctly and know when additional steps are required.

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 meaningful semantics for integration_ids by singling out case-queue-producer and case-queue-consumer integrations and explaining their runtime requirements. This goes beyond the schema's generic 'Integration IDs...' description.

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

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

The description clearly states the verb and resource: 'Attach one or more integrations to an agent revision.' It also distinguishes itself from the sibling pinRevisionIntegrationConnection by explaining that pinning is a separate follow-up action. This is specific enough for an agent to know exactly what the tool does.

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 pinRevisionIntegrationConnection for pinning connections after attachment. It also gives a clear workflow for case-queue integrations: attach → link queues via replaceRevisionIntegrationQueues → verify with getRevisionCaseQueueSetup. This is explicit when-to-use and when-to-use-alternative guidance.

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

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

It discloses permission requirements (owner vs builder) but does not mention idempotency, side effects on existing attachments, or what happens if the login is already attached. The description is partially transparent about 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 concise, two sentences long, and contains no redundant or extraneous information. It efficiently conveys the core purpose and a key constraint.

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

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

The description provides the primary purpose and permission context, but it does not mention the return value, potential errors, or behavior in edge cases. Given the lack of output schema and parameter descriptions, it is not fully complete from an agent's perspective.

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 provides no descriptions, and the tool description does not clarify the meaning of parameters like agentId, buildId, or exposedCredentialId. Users cannot infer from the description how these map to the concept of 'attach a login to a revision'.

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

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

The description clearly states the action (attach), the resource (login), and the target (revision), and explains the purpose (for use during Runs). It effectively distinguishes this from similar tools by focusing on the specific action and its intent.

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 does not explicitly state when to use this tool versus alternatives like attachRevisionSecret or detachRevisionLogin. It provides permission constraints but lacks comparison or selection criteria for an agent.

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

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

With annotations carrying only generic false hints, the description adds meaningful behavioral detail: the operational effect on Runs and the ownership/permission constraints. It does not contradict annotations and gives an agent a realistic expectation of side effects.

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

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

Two front-loaded sentences: the first states the action and effect, the second adds permission constraints. No redundant or filler content.

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

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

The description covers purpose, effect, and permissions, which is adequate for a simple mutation tool. However, with no output schema, no parameter descriptions, and no annotation details, an agent is left to infer the meaning of the three UUID parameters, so the definition is not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented agentId, buildId, and credentialId. It mentions 'secret' and 'revision' conceptually but never maps those concepts to the actual parameters or explains what each ID refers to.

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

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

The description uses a specific verb ('Attach'), names the resource ('env-var secret to a revision'), and states the expected effect ('keys are injected into Runs spawned from that revision'). This clearly differentiates it from siblings like attachRevisionIntegrations and detachRevisionSecret.

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 clear context for when this operation applies—attaching a secret to a revision for injection into Runs. It adds permission conditions for personal vs team-shared secrets, though it does not explicitly name alternatives or when-not-to-use cases.

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

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

The description adds meaningful behavioral context beyond the annotations: it reveals an interactive browser step, that the tool returns an authorization URL, that user consent is required, and that Duvo creates the connection afterward. These are important operational traits that annotations alone do not convey. It does not contradict the annotations.

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

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

The description is a single, dense sentence that front-loads the purpose and then explains the full flow. Every phrase earns its place: the method (Dynamic Client Registration), the intermediate result (authorization URL), the required user action, and the final outcome (connection creation and redirect). No filler or redundancy.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is largely complete: it explains the interactive nature, the side effect of creating a connection, and the returnUrl behavior. It does not cover failure scenarios or mention prerequisites like required capabilities, but the schema covers parameter-level details well enough.

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

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

Schema description coverage is 100%, so the individual parameters are already fully documented. The description adds some context by mentioning Dynamic Client Registration and the optional returnUrl behavior, but it does not substantially explain parameters beyond what the schema provides. 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 states a specific verb and resource: 'Start an OAuth-based connection with a remote MCP server using Dynamic Client Registration.' It clearly explains the tool's core function and outcome (returns an authorization URL, creates a connection after consent). However, it does not explicitly distinguish itself from sibling tools like startNativeOAuth or checkMcpOAuth, so it stops short of a 5.

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

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

The usage context is reasonably implied: use this tool when you need to establish an OAuth connection to a remote MCP server. Yet the description never explicitly names alternatives, such as startNativeOAuth or probeMcpServer, or states when not to use this tool. This leaves the agent to infer routing from tool names rather than from explicit guidance.

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

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

Annotations already declare non-readOnly, non-idempotent, non-destructive, openWorld. The description goes beyond them by disclosing a side effect not visible in the schema (email entries can create invitations) and the per-outcome result taxonomy (success, conflict, delivery failure). It still omits auth/permission requirements and partial-failure semantics.

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

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

Two sentences, no filler, and the core action and batch scope are front-loaded before the side-effect/outcome detail. Every clause earns its place.

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

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

For a batch mutation with no output schema and no annotations covering safety beyond hints, the description gives the action, side effect, and outcome vocabulary, which is a reasonable core. It stops short of batch-size limits, permission requirements, and what happens when some node-person pairs fail, which matter for a 20x20-style bulk operation.

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

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

Schema description coverage is 0%, so the description carries the burden, yet it only hints at the meaning of the email field (invitations). orgId, nodeIds, and the required per-person fields name, processRole, and teamRole are never explained, leaving most parameters documented nowhere.

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 (Add), resource (people), and target (multiple Process Landscape nodes) with an explicit batch scope. It implicitly separates itself from the singular sibling addClarityLandscapeNodePerson by emphasizing 'one or more people to multiple nodes', but never names that sibling, so differentiation is left to inference.

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

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

The phrase 'bounded batch' implies this is the tool for multi-node/multi-person adds, which is usable context, but there is no explicit when-to-use/when-not-to-use guidance and no mention of the singular alternative addClarityLandscapeNodePerson. Usage is implied rather than stated.

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

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

The description claims the proposal id is a durable idempotency key and that retries return the same run, but annotations declare idempotentHint=false. This is a direct contradiction between the described behavior and the annotation metadata, which the scoring rules treat as a serious failure.

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 well-structured: it states the action, explains the input-resolution rule, covers idempotency, and describes the two relevant HTTP statuses. Every sentence adds useful information without 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?

The description covers the key operational behaviors: input selection, idempotency, asynchronous completion, and conflict handling. It does not mention how to track the resulting run or what a successful response body contains, but for a fire-and-forget async build tool the provided context is largely sufficient.

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 meaningful semantics beyond the schema by explaining that transformation_proposal_id defaults to the process's live proposal and acts as an idempotency key, giving the agent a better understanding of how the parameter controls execution.

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

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

The description clearly states the tool's function: handing an automation proposal off to the workflow-builder pipeline and building an automation from a proposal. It is specific about the resource and action, though it does not explicitly differentiate itself from sibling tools like createAutomation or updateAutomation.

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

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

The description provides clear context on how the tool selects its input: it uses transformation_proposal_id when supplied, otherwise the process's live proposal. It does not explicitly state when to use this tool versus alternative automation-creation tools, but the parameter-selection logic 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?

Beyond the annotations (readOnlyHint false, idempotentHint false), the description discloses immediate emailing, per-batch outcome categories, rollback of failed invites, and the server-controlled accept-link origin. No contradiction with annotations.

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

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

Three sentences with no filler: the main action is first, followed by the return semantics, then a clarifying note about the accept link. Every sentence earns its place.

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

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

With no output schema, the description carries the burden of explaining return values; it defines succeeded/skipped/failed and rollback. Combined with the detailed team_id parameter schema, an agent has what it needs to invoke the tool correctly without guessing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value by explaining member-level outcomes (succeeded/skipped/failed), duplicate handling within the same batch, and rollback semantics for failed emails, which the schema does not fully spell out.

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 action and resource: 'Invite several people to a team in one call, emailing each invitation immediately.' The bulk scope is explicit, which distinguishes it from single-invitation siblings such as createTeamInvite without needing to open 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?

Batch context is clear and the team_id parameter guidance is unusually specific (API keys pinned to one team should omit or pass the same team; OAuth callers should pass the target team). It stops short of explicitly naming an alternative for single invites or stating when not to use the tool, but the context is clear enough.

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

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

Annotations only cover the safety profile (not read-only, not idempotent, not destructive). The description goes well beyond that: it discloses a throughput constraint (at most a share of free sandbox capacity per call), partial-execution semantics with a `deferred` bucket to be retried, and an explicit `skipped` bucket with reasons. That is exactly the kind of capacity/rate-limit and failure-mode context annotations cannot express.

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 what the tool does before moving to the deferred/skipped semantics. No filler; each sentence carries information about execution behavior. Slightly dense but well ordered.

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 shape of the result (deferred vs skipped with reasons), which is what an agent needs to drive the retry loop. It stops short of quantifying the capacity share or saying how to detect that started runs have finished, so an agent must infer the polling step.

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 all three parameters (including both enums) are documented in the schema, so the baseline of 3 applies. The description adds no syntax or format detail beyond the schema — it mentions processes generically but never explains `kind` or `transformation_aggressiveness`.

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 snapshot generation for many v2 clarity processes') and the scope ('current team'). The word 'many'/bulk distinguishes it in spirit from the single-process sibling generateClarityProcessSnapshot, but the description never names that alternative, so differentiation is inferred rather than explicit.

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

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

It gives real operational guidance on the retry loop ('the rest come back in `deferred` and should be sent again once some of the started runs finish'), which is genuinely useful. However it never states when to use this bulk tool versus generateClarityProcessSnapshot for a single process, or any precondition about sandbox capacity being available.

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

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

Adds real behavioral context beyond the annotations: active runs are interrupted first, cases are reset to pending, and dispatch happens on the next dispatcher tick. That tells the agent what is destroyed and when the effect materializes. It omits throughput/volume limits (e.g., how many cases the all_matching path can hit) and any confirmation or return information.

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 sequencing, then prerequisites. No filler or restated name/title content.

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

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

Covers the operation, its side effects, and agent preconditions for a 6-parameter tool with nested filters and no output schema. It could say what the call returns (e.g., which/how many cases were queued) since no output schema exists to carry that, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents queue_id, agent_id, case_ids, all_matching, search, and filters. The description restates the agent_id constraint (queue consumer, same automation) but adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb+resource+scope: re-processing multiple cases on a chosen agent, with the exact mechanism (interrupt active runs, reset to pending, reassign). This distinguishes it from neighbors like bulkUpdateCaseStatus, bulkUpdateCasePriority, and startRun, which mutate status or launch a run without touching the agent assignment.

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 preconditions for use: the agent must already be a case-queue-consumer of the queue (trigger enabled or disabled) and must not belong to a different automation than the queue. It does not explicitly contrast with alternatives such as startRun or bulkUpdateCaseStatus, so it stops short of a full when/when-not routing statement.

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

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

Annotations already declare the write/destructive profile, and the description adds genuinely new semantics: priority ordering (due postponed cases first, then higher priority), that it never interrupts runs or changes status, and that `none` resets to default. It does not cover auth needs, bulk size limits, or partial-failure behavior, so it falls 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 tight sentences with no filler; the core action is front-loaded and the qualifiers (ordering semantics, non-disruption, reset) each earn their place.

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

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

For a bulk mutation tool with no output schema, the description covers the effect and its boundaries well. Minor gaps remain around bulk limits and per-case failure handling, but the essential behavior is conveyed.

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 six parameters are documented in the schema; the description re-explains the `priority` enum values and the `none` reset, which adds some but not substantial meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Set the priority of multiple cases') with the 'bulk/multiple' scope explicit. It distinguishes itself from the nearest sibling, bulkUpdateCaseStatus, by stating it 'never ... changes case status', so an agent can separate the two without reading 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?

Explains the operational context (priority governs pickup order for pending cases) and implicitly routes away from status mutation, giving clear when-to-use context. It stops short of an explicit 'use X instead when Y' exclusion statement, so it is not a full 5.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses concrete side effects an agent must know before calling: it interrupts active runs and releases case ownership, deliberately preserves human-in-the-loop state so pending requests remain answerable, archives pending requests across all attached runs when settling, and archives nothing when resetting to pending. This is exactly the kind of irreversible-consequence detail a destructive bulk 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?

The core action is front-loaded in the first sentence, and the subsequent sentences each cover a distinct consequence (run interruption, human-in-the-loop preservation, archival on settle vs reset). It is dense and longer than average, but every clause carries operational weight for a destructive bulk mutation.

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 destructive bulk operation, the description covers the critical blast-radius details (run interruption, ownership release, archival scope, re-dispatch on reset). It omits only secondary concerns such as permission requirements and partial-failure behavior, which keeps it short of a 5.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including the status enum and its reset semantics. The description's mention of the four settable statuses and the reset behavior largely restates what the schema already carries, so it adds little parameter-level meaning beyond the baseline.

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

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

The description states a specific verb+resource+scope: 'Update the status of multiple cases to pending, completed, failed, or canceled.' The bulk scope and the enumeration of target statuses let an agent distinguish it from single-case updateCase and from bulkUpdateCasePriority or bulkReprocessCases 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?

Usage is implied by 'multiple cases' (use when acting on many at once, rather than the single-case sibling), but the description never explicitly says when to prefer this over updateCase or the other bulk siblings. It gives no exclusions or prerequisites, so routing relies on 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 destructiveHint=true and idempotentHint=false, so safety is largely covered. The description adds one genuinely new behavioral detail beyond the annotations — that the sandbox is paused as a side effect — but says nothing about reversibility, resume path, or downstream effects on in-progress work.

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

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

A single front-loaded sentence with zero filler. The primary action and its side effect are both stated immediately with no 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?

Given the rich annotations (destructive, non-idempotent) and the fully documented schema that carries the important decline-instead nuance, the description is nearly complete. A brief note that cancellation is not reversible/undoable would close the remaining gap.

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

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

Schema coverage is 100% and both parameters are described in the schema, including the const status value and the uuid format. The description adds no parameter-level 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?

"Cancel a running builder run and pause its sandbox" states a specific verb (cancel), a specific resource (builder run), and even a secondary effect (sandbox pause). It clearly distinguishes from the sibling getBuilderRun and resumeBuilderRun, though it doesn't name those alternatives explicitly.

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

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

The description offers no when-to-use guidance, prerequisites, or alternatives. The useful scoping note ("review-pending changes must be declined instead") lives in the status schema property, not the description, so the description itself leaves routing entirely 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?

The description states 'Performs no writes,' which directly contradicts the readOnlyHint=false annotation. This is a serious inconsistency: the annotation implies the tool may modify state while the description asserts it never writes. Because the description contradicts structured metadata, it earns the minimum score and should be flagged.

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

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

The description is three sentences with no filler: it states the action, the return value, the intended precursor role, and the non-writing behavior. Key information is front-loaded before secondary details.

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

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

For a low-complexity single-parameter tool with no output schema, the description covers the main purpose and partially describes returns ('authorization endpoint and required scopes when supported'). However, it does not explain what happens when OAuth Dynamic Client Registration is not supported, and the annotation contradiction undermines the reliability of the tool's behavioral contract.

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 parameter mcp_server_url has 100% schema description coverage, so the schema already explains it as 'URL of the MCP server to probe for OAuth support.' The description adds no extra semantic detail beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies a specific action (probe an MCP server URL), a resource (MCP server), and a concrete outcome (discover OAuth Dynamic Client Registration support, return authorization endpoint and scopes). It does not explicitly differentiate itself from the similar sibling 'probeMcpServer', so it falls short of a 5.

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

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

The description gives clear usage context by naming the endpoints this tool is a precursor to ('/v2/teams/:team_id/connections/oauth/mcp/start' and '/v2/teams/:team_id/connections'). However, it does not mention alternatives like probeMcpServer or state when not to use it, so no exclusions are provided.

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 signal this is a non-read-only, non-idempotent operation. The description adds a useful behavioral detail: uploaded bytes are validated before the import becomes a usable capture. It does not disclose failure behavior or what happens if validation fails, but it provides more context than the annotations 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?

Two short sentences with no filler or repetition. The core action is front-loaded, and the validation step is presented as a meaningful second sentence.

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

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

The description covers the main flow and outcome, and the schema fully documents parameters, but it omits response semantics and failure behavior for validation. For a non-idempotent state-changing tool without an output schema, this is a minimal but slightly incomplete definition.

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

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

The input schema already documents all four parameters with descriptions and constraints at 100% coverage. The description adds general workflow context but no parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description identifies a specific verb ('complete') and resource ('Miro artifact import'), and adds process context about uploading to a signed URL and becoming a usable Clarity capture. It is distinguishable from sibling upload-completion tools by 'artifact import,' though it does not explicitly contrast them.

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

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

The description clearly states the temporal context: call this tool after uploading to the signed URL. It does not mention alternatives or exclusions, but the sequencing is explicit enough for an agent to understand when in the workflow this belongs.

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

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

Annotations already indicate this is a non-read-only, non-idempotent, non-destructive mutation, so there is no contradiction. The description adds the useful precondition that the upload must already have happened, but it does not disclose what state changes occur, whether repeated calls fail, or what downstream effects completion triggers.

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 sentence with the action front-loaded and the key prerequisite included. There is no redundant restatement of the schema or filler.

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

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

For a simple three-parameter completion step with fully documented parameters, the description gives the essential workflow context: this call finalizes a document capture after the GCS signed-URL upload. It does not describe return values or detailed side effects, but those are not necessary for a basic completion call given the schema and annotations.

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

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

The schema covers 100% of parameters with meaningful descriptions: id, captureId, and fileName are all explained. The description adds no parameter-level details beyond the schema, so it meets the baseline for high schema coverage without needing to compensate.

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 identifies a concrete action ('Complete a document capture') and a specific workflow step ('after uploading to GCS via signed URL'), which separates it from upload-creation tools and from image/video completion tools. It does not explicitly contrast with completeClarityOrganizationDocumentUpload or completeClarityTeamDocumentUpload, so some sibling differentiation relies on the tool name.

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

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

The phrase 'after uploading to GCS via signed URL' provides a clear temporal condition and tells the agent when in the workflow this tool should be called. However, it does not name alternative completion tools or state when to prefer the organization/team/artifact variants, leaving 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?

Annotations already establish this is a non-read-only, non-idempotent, non-destructive write. The description adds one genuinely useful behavioral trait beyond that: the hard prerequisite that the GCS upload via signed URL must happen first. However, it does not disclose what 'complete' does to the capture's state, what happens if invoked before the upload, or the consequences of calling twice (relevant given idempotentHint=false).

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 15-word sentence that front-loads the verb and object, then appends the only necessary context (the GCS signed-URL prerequisite). There is no redundancy with the title, no fluff, and every word contributes.

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

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

For a tool with 3 required params, no output schema, and no nested objects, the description covers the basic what and when. But it leaves gaps: it never references the createClarityImageUploadUrl pairing that produces the signed URL, it does not clarify how the three IDs relate to the upload flow, and with no output schema it says nothing about what a successful completion returns or triggers.

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% — each of the three parameters (id, captureId, fileName) has a description in the schema. Per the baseline for high coverage, the description need not repeat param details, and it doesn't. The description adds no extra meaning about which ID maps to which part of the flow, but the schema already carries the documentation burden adequately.

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 ('Complete') with a specific resource ('an image capture') and adds the scoping context ('after uploading it to GCS via a signed URL'). This cleanly distinguishes it from the sibling family: completeClarityVideoUpload, completeClarityDocumentUpload, and the other complete* tools differ by resource type (image vs video vs document/artifact).

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

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

The phrase 'after uploading it to GCS via a signed URL' gives clear sequencing context: this is the second step of a two-phase flow, implicitly paired with a URL-creating tool like createClarityImageUploadUrl. It does not explicitly name alternatives or state exclusions (e.g., 'use completeClarityVideoUpload for videos'), so it stops short of full when-not-to-use guidance.

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

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

Annotations already mark it non-read-only and non-destructive; the description adds useful behavioral context by stating it extracts text, stores a transcript, and feeds Process Landscape generation. It does not mention idempotency consequences, but idempotentHint=false already signals that risk.

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 states the action, the precondition, the processing behavior, and the downstream consumer with no filler. Every clause contributes to helping the agent decide and invoke 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?

For a 3-parameter, multi-step completion operation with no output schema, the description covers the main workflow and downstream outcome, which is enough for a capable agent. The main gap is that it does not describe the return value or what happens on failure, but these are minor against the clear purpose and schema coverage.

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

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

The schema describes interviewId and fileName but leaves orgId undocumented at 67% coverage. The description does not add parameter-specific meaning or explain how orgId/interviewId/fileName relate to the capture, so it neither compensates for the missing orgId description nor enriches the covered parameters.

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

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

The description uses a specific verb ('complete'), identifies the resource ('organization document capture'), and defines what completion entails: text extraction and transcript storage for Process Landscape generation. This distinguishes it from sibling upload-completion tools like completeClarityTeamDocumentUpload or completeClarityImageUpload.

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 clear precondition ('after uploading to GCS') and implies the organization-document workflow, but it does not name alternatives or say when not to use it. An agent must infer that this is the org-specific counterpart to completeClarityDocumentUpload rather than being told.

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 discloses the key state-changing behavior beyond the annotations: it 'extracts text and stores it as a transcript'. This aligns with readOnlyHint=false and destructiveHint=false, and adds useful context about what happens when the tool is invoked. It does not discuss idempotency or failure modes, but the core behavioral trait is transparent.

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

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

The description is a single sentence that front-loads the action and context, then states the purpose. Every clause earns its place: the GCS precondition, the extraction/storage behavior, and the downstream use. There is no extraneous information.

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

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

For a tool with no output schema and three well-documented parameters, the description gives the essential operational context: when to call it, what it does, and why it matters. It could mention return behavior or error conditions if the GCS upload hasn't happened, but those are not critical for basic 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?

Schema description coverage is 100%, so the input schema already documents interviewId, fileName, and team_id thoroughly. The tool description adds no additional parameter-specific meaning, which is acceptable at the baseline given the schema's strong coverage.

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

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

The description names a specific verb ('Complete'), a specific resource ('team document capture'), and the concrete outcome ('extracts text and stores it as a transcript'). The phrase 'after uploading to GCS' clearly situates it in a two-step upload pipeline, and 'team' distinguishes it from sibling tools like completeClarityDocumentUpload and completeClarityOrganizationDocumentUpload.

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

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

The description gives a clear sequential context: use this after the file has been uploaded to GCS. It also signals downstream relevance by noting the transcript 'feeds Process Landscape generation'. It does not explicitly enumerate when-not-to-use or name alternative sibling tools, but the team-specific wording makes the intended context clear.

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

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

Annotations already signal that this is a non-read-only, non-idempotent mutation, so the description does not need to repeat those hints. It adds the useful sequencing context that the upload must already have happened, but it does not disclose what 'complete' does to the capture (e.g., status transition, validation, irreversibility).

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

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

The description is a single, front-loaded sentence with no filler. It leads with the action and resource, then adds the essential precondition, making it efficient for an agent to parse.

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 tool with no output schema and no nested objects, the description plus schema is adequate to invoke the tool: it names the action, the resource, and the required precondition. It could be more explicit about what completing the upload entails or that it pairs with createClarityVideoUploadUrl, but nothing essential 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?

The input schema already documents all three parameters with clear descriptions (clarity process ID, capture ID, uploaded file name) at 100% coverage. The description adds no parameter-specific semantics beyond tying fileName to the GCS upload flow, 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 states a specific action ('Complete a video capture') and the resource ('video capture'), with an explicit precondition ('after uploading to GCS via signed URL'). The word 'video' plus the completion-vs-creation verb clearly sets it apart from sibling tools like createClarityVideoUploadUrl and the other complete* upload variants.

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 indicates the triggering condition: the tool should be called only after the video file has been uploaded to GCS via a signed URL. It does not explicitly name alternative tools or list when-not-to-use scenarios, but the context is sufficient for basic selection.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, but the description adds two traits those hints do not convey: the change is staged into a *draft* revision (not applied live), and consuming a suggestion auto-clears other pending suggestions made moot. That side effect is exactly the kind of non-obvious behavior an agent needs to know before calling.

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

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

A single tight sentence that front-loads the core action and then the side effect. No wasted words, though the placement of the auto-clear behavior at the end slightly buries a consequential detail.

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

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

For a destructive, non-idempotent mutation with no output schema, the description nails the mechanism and side effect but leaves two of four parameters unexplained and offers no routing to sibling tools. It is adequate for the happy path but incomplete for correct invocation in edge cases.

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

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

Schema coverage is only 50% — id and selected_automation_revision_id are documented, but revision_id and create_new_draft are undocumented in both schema and description. The description says nothing about any parameter, so it fails to compensate for the gap; an agent cannot tell what revision_id or create_new_draft do.

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

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

The description gives a specific verb+resource ('Apply a suggestion') and explains the mechanism (stage its change into the Agent's draft revision). It distinguishes itself implicitly from rejectAgentSuggestion and getAgentSuggestion, though it never names those siblings explicitly, so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternatives (rejectAgentSuggestion, getAgentSuggestion, listAgentSuggestions). The agent must infer the invocation context from the name alone.

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

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

Annotations already declare write, non-idempotent, non-destructive, so the bar is lower. The description still adds real value beyond them: the created agent's first build is a draft in the automation's draft revision and only goes live when that draft is made active — a non-obvious side effect an agent would otherwise miss. It stops short of stating return contents or auth requirements (team pinning lives only in the schema).

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

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

Three sentences, front-loaded with the action, then the optionality, then the non-obvious release semantics. No filler and no repetition of schema content.

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

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

For a seven-parameter, deeply nested creation tool with rich schema coverage and safety annotations already present, the description covers the essential behavioral nuance. The only gap is that no output schema exists and the description never says what a successful call returns (presumably the new agent with its ID).

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

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

Schema description coverage is 100%, so all seven parameters, including nested build/config fields, are already documented in the schema. The description only abstracts the build parameter's optionality and doesn't add format or constraint details beyond it — 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?

"Create a new agent" is a specific verb+resource, and the second sentence scopes the optional build creation. An agent can distinguish this from updateAgent, duplicateAgent, and createRevision 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 conveys when the inline build path applies ("create the first build in the same request") and the automation-draft context, which implies usage. But it names no alternative (e.g. createRevision for later builds, or that code steps must use a different endpoint — that exclusion lives only in the schema), and gives no explicit when-not guidance.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false). The description adds valuable behavioral context beyond that: the at-most-one invariant and the specific 409 failure mode when a trigger already exists. It does not detail success behavior or side effects, but the conflict behavior is a strong disclosure.

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

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

Two sentences, no filler. The primary action is front-loaded, and the important uniqueness/conflict constraint follows immediately. Every sentence adds useful information.

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

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

The schema comprehensively documents all four parameters, and the description supplies the key behavioral constraint for a create operation. The main gap is that it does not describe the successful response shape or explicitly guide the agent toward update/upsert alternatives when a trigger already exists, but these are minor for this 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?

Input schema coverage is 100%, so the description does not need to restate parameter meanings. The description adds no parameter-specific semantics beyond what the schema already provides; it only describes a trigger-level constraint.

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

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

The description states a specific action and resource: 'Create a case trigger for an agent.' It clearly differs from sibling tools by specifying 'case trigger' rather than, say, a Slack trigger, and it adds the meaningful uniqueness constraint that an agent can have at most one.

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

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

The description implies this tool is for creating a new case trigger and that an existing trigger will cause a 409. However, it does not explicitly mention alternatives such as updateAgentCaseTrigger or upsertAgentTrigger, nor does it say when to prefer one over the others.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description adds no behavioral context beyond the creation act itself. It does not mention side effects, return values, uniqueness constraints, or how the folder relates to agents. No contradiction with annotations.

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

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

The description is a single front-loaded sentence with no filler, which is appropriate for a simple create operation. However, it is minimal enough that it essentially restates the title, so it does not quite reach the highest tier.

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

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

The definition is largely sufficient given the fully documented schema and simple semantics. However, there is no output schema, and the description does not indicate what a successful creation returns or how the new folder is subsequently used, leaving some ambiguity for an agent.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including detailed team_id and parent_folder_id semantics. The description itself adds no parameter-level detail, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Create a new agent folder.' This is unambiguous and clearly distinct from siblings like createAgent or createClarityFolder by resource type, though it does not explicitly name those alternatives.

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

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

No guidance is given about when to use this tool versus related tools such as listAgentFolders, updateAgentFolder, deleteAgentFolder, or moveAgentsToFolder. There are no usage conditions, exclusions, or alternative routing.

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

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

Annotations only convey read/write/idempotency/destructiveness flags. The description goes beyond them by explaining the trigger's side effect (a Run starts on matching messages), the one-trigger-per-channel limit, the binding prerequisite, and the 400 failure mode. This is substantial extra behavioral context.

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

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

Three sentences carry all operative information with no filler: purpose/behavior, cardinality constraint, and prerequisite/failure. The most important scoping guidance is front-loaded.

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

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

For an 8-parameter create operation with no output schema, the description covers what happens on success, the per-channel limitation, prerequisite setup, and the error condition, while the schema documents every parameter. There are no invocation requirements 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?

Schema coverage is 100%, with each of the 8 parameters already described by name, format, defaults, and examples. The description reinforces the general matching and per-channel concepts but adds no parameter-specific semantics beyond the schema, 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 — 'Create a Slack channel trigger on an agent' — and then defines the tool's effect as starting a Run when a matching message is posted. Naming 'Slack channel trigger' distinguishes it from sibling case-trigger tools such as createAgentCaseTrigger.

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 operational conditions: call once per channel, and only after the Slack workspace is installed and bound to the agent's live build, with a 400 failure otherwise. It doesn't explicitly contrast with alternatives like upsertAgentTrigger or updateSlackTrigger, so it stops short of full routing guidance.

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

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

Annotations already declare this is a non-destructive, non-idempotent write. The description adds substantial non-obvious behavior: an agent is created alongside the automation, `first_agent` seeds that agent, and revision semantics vary by team type, including draft-creation and activation behavior. It does not cover permissions, error cases, or return values.

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

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

Three sentences, front-loaded with the core action and its main side effect. The revision-semantics sentence is long but earns its place by explaining a non-obvious branching behavior; no obvious filler is present.

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

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

The description does well on creation semantics and revision behavior for a complex nested tool, and the rich schema covers parameters. However, with no output schema, it says nothing about what the caller receives back after creation, nor about permissions or failure modes — a meaningful gap for a create endpoint.

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 schema already documents `name`, `team_id`, and the deep `first_agent` structure. The description reinforces that `first_agent` seeds name, configuration, and connections instead of defaults, but adds only marginal meaning beyond the schema.

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

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

The description states a specific verb and resource: 'Create a new automation.' It adds that a first agent is created alongside it, which distinguishes the operation from a bare agent-creation call, though it does not explicitly name sibling tools like createAgent or duplicateAutomation.

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 purpose — starting an automation with an immediately editable first agent — but the description gives no explicit 'use this when' or 'use X instead' guidance. It also omits any mention of alternatives such as createAgent, duplicateAutomation, or buildClarityAutomation.

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 meaningfully beyond the sparse annotations (all false hints) by disclosing that the tool issues a signed URL and that the attachment does not become visible until the finalize endpoint is called — a genuinely non-obvious two-phase behavioral trait. It also specifies the PUT-with-Content-Type requirement, which an agent could not infer from the schema. Signed-URL expiry and authorization needs are not mentioned, but the core behavioral disclosure is strong.

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

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

Two sentences, roughly 50 words, with the core purpose front-loaded in the first sentence and the essential follow-up protocol in the second. Every clause earns its place; there is no filler or restatement of the title.

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 moderate-complexity tool with no output schema and minimal annotations, the description conveys the critical facts: what is returned (signed URL and Content-Type), the exact PUT protocol, and the dependency on the finalize endpoint. Minor omissions — signed-URL expiry, explicit size-limit emphasis, and failure behavior — leave some room, but the core flow is fully actionable.

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

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

Schema description coverage is only 40% (case_id and queue_id), so the description must partially compensate for filename, mime_type, and size_bytes. It adds real meaning by tying mime_type to the 'returned Content-Type' and framing the file fields as the payload to PUT, but it does not individually explain their constraints or semantics, leaving the 50MB size ceiling and length limits solely to the schema.

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

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

States a specific verb and resource — 'Issue a signed URL for uploading a file to a case' — which is unambiguous and anchored to the case domain, distinguishing it from generic upload-URL siblings like createFileUploadUrl. The finalize-step mention further scopes its role. It does not explicitly name a sibling for disambiguation, but the case-specific framing is sufficient.

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

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

Provides explicit protocol guidance: the client 'must PUT the bytes to the returned URL with the returned Content-Type, then call the finalize endpoint,' which tells an agent exactly how to consume the result and that a mandatory follow-up call exists. It does not state exclusions or route among alternatives such as createFileUploadUrl, but the intended usage context is clearly conveyed.

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 carry only the generic safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds exactly the kind of context annotations cannot: the 409 precondition tied to first settled case, and the version-cap ceiling with its two values and the fact that the error message reports it. This is rich, non-obvious failure-mode disclosure.

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 core action in the first sentence, then layers the definition and the two constraints. The single dense paragraph with em-dashes is information-rich but a touch packed; every clause still earns its place, so a 4 is fair.

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 create tool with no output schema, the description covers what is created, where it lands (current build-set version), the precondition for success, and the hard limit. Nothing an agent needs in order to call it correctly or interpret common failures is missing.

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

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

Schema description coverage is 100%, and all three parameters (title, queue_id, description) are documented with lengths and format in the schema itself. The description adds conceptual meaning (Pass/Fail at settlement) but no per-parameter guidance 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 ("Add") plus a precise resource ("one case-level evaluation rubric to a queue's current rubric set") and explains what a case-level rubric is judged against. An agent can distinguish it from sibling tools like createEvalRubric, replaceCaseQueueEvalRubrics, and updateCaseQueueEvalRubric without opening any schema.

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

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

Gives clear situational context: the queue must already have settled an Agent-processed case or this fails with 409, and the version ceiling (12 by default, 25 with the newer generator) determines when additions stop. It does not, however, explicitly route the agent to alternatives like replaceCaseQueueEvalRubrics for bulk replacement, so it earns 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?

The description extensively discloses behaviors: mutual exclusivity of case/cases and data/json_data, label creation on the queue, priority semantics affecting pending order, validation against the queue's Case schema, and the 400 error condition. Annotations already indicate this is a mutating, non-destructive operation; the description adds rich context about validation and side effects, exceeding what annotations provide.

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

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

The description is long but well-structured, front-loading the core action and then detailing conditions and rules. Every sentence contributes necessary information for the tool's complexity. It could be more concise by trimming some conditional clauses, but the organization is logical and readable.

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 (nested objects, multiple exclusive modes, schema validation, priority behavior), the description covers all essential aspects: limits, error conditions, data format selection, and queue-specific rules. It doesn't describe return values, but no output schema exists and creation tools typically return minimal info; the description is sufficient for an agent 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?

Despite only 33% schema description coverage, the description explains the meaning and interaction of all key parameters: the case/cases structure, the 1-100 array limit, the mutual exclusivity of data and json_data, priority enum semantics, and label behavior. This adds substantial meaning beyond the schema's field descriptions, especially for the tricky conditional rules around schema-guarded queues.

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 clear, specific action: 'Create one or more cases in a queue.' This states the verb, resource, and context, and it differentiates from sibling tools like updateCase, deleteCase, and searchCases. The tool's purpose 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?

While the description doesn't explicitly contrast with sibling tools, it provides detailed guidance on when to use a single case vs. an array, and when to use free-form data vs. structured json_data based on queue schema guards and automation context. This is strong usage guidance for the tool's own variants, though it omits explicit 'use this instead of X' 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 description discloses a non-obvious two-step behavior: this tool only creates the URL; the caller must separately upload and then complete the import. This goes beyond the minimal annotation set, which only says readOnlyHint=false and destructiveHint=false. It does not mention expiration or side effects, but the core workflow is transparent.

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

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

Three sentences, each earning its place: the first states the operation, the second lists supported formats, and the third explains the required follow-up. The most important scoping information is front-loaded.

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

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

With no output schema, the description still makes clear that a URL is returned for uploading and that a completion step is required. It could name the exact complete-import sibling tool or describe the response shape, but the essential context for invocation and next steps 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%, so the schema already documents process_id, file_name, content_type, and extra_capture_request_id. The description reinforces the supported file types but does not add meaningful parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb, resource, and scope: 'Create a signed upload URL for importing a Miro export into a Clarity v2 process.' It names the supported formats and, by focusing on Miro artifacts, is distinguishable from sibling tools like createClarityDocumentUploadUrl and createClarityImageUploadUrl.

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

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

The description gives clear workflow context: the caller must upload the file to the returned URL and then complete the import. It does not explicitly name alternatives or exclusion conditions, but the Miro/Clarity-v2 framing is specific enough to guide selection.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-obvious context: the URL is signed and the upload target is GCS directly. It omits URL expiration, HTTP method, and that a completion call is required, so it only partially exceeds the annotation floor.

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 no boilerplate. The enumerated accepted formats partly duplicate the contentType enum, a minor redundancy, but the sentence still earns its place.

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

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

No output schema exists, so the description carries the burden of describing the return, and "signed URL" only hints at it. For an upload-flow tool it should mention expiry, upload method, and the completion step; given the annotations cover safety and the schema covers inputs, this is adequate but with clear gaps.

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

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

Schema description coverage is 100%, so all four parameters (id, fileName, contentType, extraCaptureRequestId) are already documented, establishing a baseline of 3. The file-type list in the description loosely maps to the contentType enum but adds no format or constraint detail beyond it, and extraCaptureRequestId is never mentioned.

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 signed URL") scoped to Clarity document uploads, and the enumerated file types (PDF, docx, TXT, Markdown, BPMN, XLSX, CSV) signal that this is the document variant rather than image/video. It does not explicitly name createClarityImageUploadUrl, createClarityVideoUploadUrl, createClarityTeamDocumentUploadUrl, or createClarityOrganizationDocumentUploadUrl, which are easy to confuse given the crowded upload-url sibling set.

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

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

No when-to-use or when-not guidance, and no indication of the prerequisite (existing Clarity process id) or the required follow-up. The workflow implication that a signed URL must be followed by completeClarityDocumentUpload is absent, despite that sibling existing.

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

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

The annotations already indicate this is not read-only, not idempotent, and not destructive, and the description adds no behavioral context beyond the word 'create.' It does not disclose side effects, naming collisions, permissions, or what kind of object is produced, so the description adds little beyond the structured metadata.

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

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

The description is a single, efficient sentence with no filler or repetition. It is front-loaded and easy to parse, though it is minimal to the point of under-specification in other dimensions.

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

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

For a simple two-parameter create operation with a rich schema, the description is minimally adequate: the agent knows it creates a folder and needs a name. However, it lacks context about what a process folder is used for, whether folders are hierarchical, and what the tool returns, leaving some ambiguity for an agent navigating a large sibling toolset.

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 parameter descriptions already document the 'name' field and thoroughly explain 'team_id', including API-key and OAuth behavior. The tool description adds no extra parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description states a clear action and object: 'Create a process folder.' It is not a tautology and the verb 'create' maps directly to the tool's function. However, it does not differentiate from sibling folder tools such as createAgentFolder or clarify what a 'process folder' is within the Clarity domain.

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

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

The description provides no guidance on when to use this tool versus alternatives like createAgentFolder, setupClarityFoldersFromLandscape, or updateClarityFolder. There is no mention of prerequisites, team context, or folder hierarchy, leaving the agent to infer usage from the name alone.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the tool is understood to mutate state, but the description adds no behavioral context: it does not state whether creation is idempotent, whether it appends to existing guidance, what side effects occur, or what happens on duplicate IDs. For a mutation tool with minimal annotation detail, this is a significant gap.

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

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

The description is a single concise sentence, which is efficient. However, it is a near-restatement of the tool name and title, providing little additional value beyond what the structured metadata already conveys.

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

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

The tool has two required parameters and no output schema, and the description omits important context such as whether the guidance is appended or replaces existing guidance, whether a clarity process must already exist, or what the response/result indicates. The description is minimally adequate for basic invocation but incomplete for confident use.

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 both parameters and their types. The description adds the phrase 'automation guidance message', slightly clarifying the content field's purpose, but does not add meaning beyond the schema's own descriptions.

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

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

The description states a specific verb ('Create') and resource ('automation guidance message for a clarity process'), making the basic action clear. However, it does not distinguish itself from sibling create_* tools or from updateClarityGuidance, and the term 'clarity process' is domain-specific without elaboration.

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

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

No guidance is given about when to use this tool versus updateClarityGuidance or other createClarity* tools. The context of a clarity process and automation guidance is implied by the name and schema, but there is no explicit usage context, prerequisites, or alternatives.

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

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

Annotations mark the tool as readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining behavior. It states the tool creates a signed URL for direct GCS upload, which implies the actual upload happens client-side, but it does not disclose URL expiry, return format, or other side effects. This is adequate but not rich.

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

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

The description is a single sentence with zero filler. The core action ('Create a signed URL') and key scope (image formats, GCS) are concentrated and front-loaded. This is ideal for a low-complexity utility 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?

For a straightforward utility with fully documented parameters and no output schema, the description covers the essential purpose and scope. It could explicitly note that this only generates the URL without uploading the image, but that is already implied by 'signed URL for uploading'. The optional extraCaptureRequestId is documented in schema, so nothing essential is missing.

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

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

Schema description coverage is 100% – all parameters (id, fileName, contentType, extraCaptureRequestId) are documented in the schema. The description adds no additional parameter-level meaning beyond what is already in 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 clearly states the action ('Create a signed URL'), the resource (an image upload URL), and the scope (PNG, JPEG, WebP, SVG images, direct to GCS). This distinguishes it from sibling URL creators like createClarityDocumentUploadUrl or createClarityVideoUploadUrl by explicitly listing image formats, so an agent can reliably identify 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 implies usage through the listed image formats, but it gives no explicit guidance on when to prefer this tool over siblings like createFileUploadUrl or createClarityDocumentUploadUrl. There are no alternative names or exclusion conditions. The agent must infer the use case from the format list alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the crucial specific: creating a new link invalidates any prior active link for the process, i.e. exactly what gets destroyed. It also discloses the authorization requirement. It stops short of 5 because it says nothing about the return value or the shape of the created link, which matters since no output schema exists.

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

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

Two sentences, no filler, with the core action front-loaded followed immediately by the permission constraint and the destructive side effect. Every clause earns its place.

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

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

For a single-parameter mutation whose annotations already flag it as destructive, the description covers action, authorization, and the invalidation side effect well. The one gap is the missing description of what is returned (a link, its scope, expiration), which is more noticeable given there is no output schema.

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

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

There is a single required parameter (process_id) with 100% schema description coverage, so the schema already carries the semantics. The description's phrase "process-scoped" corroborates the parameter but adds no format, constraint, or sourcing detail beyond the schema — the expected baseline of 3.

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

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

The description names a specific verb and resource ("Create or regenerate a process-scoped Clarity interview invite link") and adds the regeneration capability, which cleanly separates it from sibling tools like createClarityProcessLink and createTeamInviteLink. It does not explicitly name those alternatives, so it stops short of full sibling differentiation.

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

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

It states a real precondition — only the process creator or team managers can create invite links — which tells the agent when this call will succeed. What's missing is routing guidance: it never says when to prefer this over sendClarityInterviewInvites, getClarityProcessInviteLink, or the delete counterpart.

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 the write flags; the description adds the real behavioral constraint — the authorization tiers required for an active area versus a proposal. It does not mention side effects of creating an active area (duplicate detection, whether an existing area is returned), which the schema partially covers.

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

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

Two sentences, no filler, with the core action front-loaded and the mode/permission caveat immediately after. Every clause carries information an agent needs.

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

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

For a mutation tool with no output schema and six parameters, the description covers permissions and mode selection but leaves the hierarchy semantics (parentId null behavior) and the result of the call unaddressed. Adequate but with visible gaps.

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

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

Schema coverage is only 33%, so the description must carry more weight than it does. It explains creationMode well (default, what proposal means, permission implications) but adds nothing about parentId (is null the root?), ownerLabel, orgId, or name constraints.

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 an area folder in the process tree.' An agent can tell what object is produced, though the description does not explicitly distinguish this from near-siblings like createClarityFolder or createClarityProcessNode.

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

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

Gives a concrete decision rule for the active vs proposal modes tied to permissions, which is exactly the branch an agent must choose. It stops short of naming alternative tools (e.g. proposeClarityLandscapeProcess) for when a proposal is the better route.

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 a non-destructive, non-idempotent, closed-world write. The description adds useful context (it returns a signed URL, and only five document formats are accepted), but omits whether the URL expires, what auth/permissions are needed, and why calls are non-idempotent (each call mints a new URL).

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?

Single front-loaded sentence, no filler, and the scope qualifier ('organization-level') arrives before the trailing details. Every phrase earns its place.

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

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

For a mutation with no output schema, the description conveys the core action and format constraints but leaves the two-step upload workflow unspecified: it never says the returned signed URL must be used to PUT the file and then finalized via completeClarityOrganizationDocumentUpload, nor does it mention URL lifetime.

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 67%, so the schema documents fileName and contentType. The description earns extra credit by mapping the raw MIME enum to human-readable formats, notably clarifying that BPMN corresponds to application/xml, which is not obvious from the enum alone. orgId remains undocumented anywhere but is self-describing.

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 (Create) and resource (signed URL for document upload) and scopes it as 'organization-level Clarity capture', which separates it from the team-level and unqualified document-upload siblings. It does not explicitly name or contrast those siblings, but the scope qualifier is enough to route an agent correctly.

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

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

No guidance on when to choose this over createClarityDocumentUploadUrl or createClarityTeamDocumentUploadUrl, and no mention of the required follow-up step (completeClarityOrganizationDocumentUpload). Usage is only implied by the phrase 'organization-level'.

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

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

The annotations only declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds useful behavior beyond those: optional name defaults server-side, and the response uses camelCase createdAt for existing FE clients. However, it does not disclose potential side effects, error behavior, or what else the response contains, so the added transparency is modest.

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

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

The description is two sentences with no filler. The first sentence front-loads the core action and scope, and the second covers the only server-side default plus a response-format note. Every sentence contributes actionable information.

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

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

For a create tool with two optional parameters and no output schema, the description covers the basic purpose, team scope, name default, and one response-format detail. However, the full return payload is only hinted at via 'createdAt', and failure conditions such as team mismatch are only present in the schema. It is adequate but not complete.

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

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

Schema description coverage is 100%, and the schema already documents both parameters thoroughly, including the team_id pinned-team fallback and OAuth behavior. The description only repeats the name defaulting and omits team_id entirely, so it adds no meaningful parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific action and resource: 'Create a new Clarity v2 process for the current team (Builder+)'. This unambiguously distinguishes the tool from sibling tools like duplicateClarityProcess, createClarityProcessLabel, and createClarityProcessNode. The 'v2' and 'current team (Builder+)' qualifiers add useful precision.

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

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

The description implies the primary use case (creating a new Clarity process) and notes the team scope, but it does not explicitly compare against alternatives like updateClarityProcess or duplicateClarityProcess, nor does it state when not to use this tool. The context is clear enough to infer usage, but no direct routing guidance is provided.

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

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

Annotations already indicate this is a non-read-only write operation, and the description adds little beyond that. It does not disclose side effects, permissions, uniqueness behavior, default colorHue application, or whether the operation is idempotent despite the idempotentHint being false.

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 single sentence is front-loaded and contains no filler. Every word adds meaning: the action, the resource type, and the organizational scope are all present.

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

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

The tool has three parameters, no output schema, and minimal annotations, so the description carries a heavy burden. It fails to mention what the tool returns, how colorHue is used, what happens on duplicate values, or any prerequisites, leaving an agent under-equipped to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate, but it only loosely maps 'organization' to orgId and 'tags' to value. colorHue is completely absent from the description, and no parameter-level constraints or defaults are explained.

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

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

The description states a specific action ('Create'), a clear resource ('process tags' / Clarity Process Label), and a scope ('for an organization'). This distinguishes it from related tools like assignClarityProcessLabels, updateClarityProcessLabel, and deleteClarityProcessLabel, though it doesn't explicitly name them.

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

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

No guidance is given on when to use this tool versus alternatives such as listAvailableClarityProcessLabels, assignClarityProcessLabels, or updateClarityProcessLabel. The description only implies creation, but doesn't address reuse, duplication, or relationship to process-process label assignment.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not fully idempotent. The description adds useful behavioral context beyond those hints: the caller permission requirement and the duplicate-handling behavior that returns the existing link. There is no contradiction with the annotations because the idempotentHint=false refers to the general operation, while the description narrows idempotency to the case of an existing live source, target, and type.

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

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

The description is two sentences with no filler. The action and permission condition are front-loaded, and the second sentence provides a valuable edge-case behavior. Every sentence contributes useful information for tool selection and invocation.

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 the tool's complexity, the description covers the core purpose, the critical permission prerequisite, and the duplicate-link behavior. Required parameters and their types are already in the schema. The description could be slightly more explicit about the meaning of 'live' and what happens when the caller lacks management rights, but these are minor gaps given schema coverage and annotations.

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

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

Schema description coverage is high (83%), so the schema already documents most parameters. The description reinforces the importance of source, target, and type in the duplicate-check condition, but it does not add meaning beyond the schema for parameters like state, confidence, or orgId. This meets the baseline for good schema coverage without adding extra parameter-level detail.

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

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

The description states a clear action ('Create a process-to-process link') on a specific resource ('the organization's Clarity landscape'). It distinguishes this tool from siblings like createClarityProcessNode and createClarityProcessLabel by specifying that the link connects two process nodes, and it adds the uniqueness behavior for existing links.

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

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

The description gives an explicit usage condition: the caller must be able to manage both endpoint teams. It also explains the behavior when the same source, target, and type already exist, which tells the agent that this tool is safe to call in that scenario. However, it does not explicitly name an alternative tool such as updateClarityProcessLink or state when not to use this tool.

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