Duvo MCP

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

Annotations already indicate a mutating, non-idempotent operation. The description adds meaningful behavioral context by stating that a durable capture request is created and that manager+ permission is required, going beyond the raw annotation flags.

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, focused sentence that front-loads the action and object, then states the outcome and permission requirement. There is no wasted text.

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

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

The description covers the core purpose, permission, and outcome, but does not explain the two required parameters or mention alternatives like dismissal. Given no output schema and no parameter descriptions, the definition is adequate but has clear gaps for an agent 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?

Schema description coverage is 0%, so the description must compensate for explaining nodeId and suggestionId. It does not explicitly map either parameter to its meaning, though 'pending Process Landscape capture suggestion' partially implies suggestionId. The nodeId role is left entirely to inference.

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'), a specific resource ('pending Process Landscape capture suggestion'), and the resulting outcome ('create the durable capture request'). It clearly differentiates from siblings like dismissClarityCaptureSuggestion and acceptClarityTeamAssignmentSuggestion by naming the Process Landscape capture suggestion scope.

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

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

The description provides clear context for when to use the tool: when a Process Landscape capture suggestion is pending and the user has manager+ permissions. It does not explicitly name alternatives or exclusions, but the role and state requirements give sufficient guidance for 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?

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?

The description discloses a significant side effect: supplying an email gives the person access and sends an invitation. It also explains that name-only records a placeholder without access. This goes beyond the annotations (which only indicate readOnly, destructive, idempotent flags) and informs the agent of the consequence of including an email. However, it does not mention other potential effects like team membership or failure modes.

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, well-structured sentence. It concisely states the main purpose, introduces the key caveat about email, and provides a clear instruction. There is no redundancy or unnecessary 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?

The description covers the core action and important side effect, which is sufficient for an agent to understand what the tool does. It does not mention the return value or output (no schema provided), nor does it explain the optional team parameters. However, for a mutation tool, the essential behavior is captured. The missing details about teamRole and teamId are less critical for basic usage.

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 low coverage (only nodeId has a description). The description adds meaning to 'name' (placeholder) and 'email' (triggers access/invitation), but does not explain orgId, teamId, teamRole, or role. Since the schema only describes 14% of parameters, the description only partially compensates, leaving several parameters ambiguous.

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 'Add a person' and the resource 'process landscape node'. It also distinguishes from sibling tools like batchAddClarityLandscapeNodePeople by implying a single-person add, and from updateClarityLandscapeNodePerson by indicating an add operation. The mention of email invitation further clarifies the purpose.

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

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

The description provides specific guidance on when to supply an email ('only pass an email the user asked you to invite'), which is a key usage decision. It implicitly differentiates from batch add by being singular, but does not explicitly state when to prefer this tool over update or batch variants. The email instruction is actionable and prevents unintended side effects.

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?

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 indicate readOnlyHint=false and destructiveHint=false, and the description adds useful behavior beyond that: the null-to-unassign semantic and the admin/manager restriction. It does not describe side effects on request status, but the core mutating behavior and permission boundary are disclosed without contradicting annotations.

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

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

The description is two sentences with no filler. It front-loads the primary action, then immediately covers the null unassignment case and the permission restriction. Every sentence earns its place.

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

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

For a four-parameter mutation tool with no output schema, the description covers the essential context: what action to perform, the special null case, and who is allowed to perform it. It could add more context about workflow sequence or relationship to sibling tools, but it is largely complete for invoking the tool correctly.

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

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

Schema description coverage is 100%, and each parameter already has a clear description. The description mostly reiterates the `user_id: null` unassignment semantics already present in the schema, and adds no extra meaning for process_id, request_id, or transformation_proposal_id. Baseline 3 is appropriate because the schema handles 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 states a specific verb and resource: 'Assign (or unassign, with `user_id: null`) a team member to fulfil an extra-capture request.' It clearly identifies what the tool does and differentiates it from sibling tools like assignClarityLandscapeCaptureRequest by the explicit 'extra-capture request' target.

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

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

The description gives clear context for when to use the tool: to assign or unassign a team member, with the unassign condition explicitly tied to `user_id: null`. It also states the role restriction ('Restricted to admins and managers'). It does not explicitly name alternative tools or when not to use them, so it stops short of a 5.

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

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

Annotations already indicate this is a write operation (readOnlyHint: false) and not destructive. The description adds meaningful behavioral detail by specifying the manager+ permission requirement and the null-userId unassignment mechanism, which are not present in the schema or annotations.

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

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

The entire description is one efficient sentence that front-loads the primary action, states the object, and adds the unassignment variant plus permission level. Every clause earns its place with no filler.

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

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

The description covers the core behavior, target state, permission, and null-unassign case, which is enough for tool selection. However, with no output schema and no explanation of nodeId or requestId, an agent may still need domain context to invoke correctly, and there is no mention of behavior if the request is already assigned.

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 explain the parameters. It clearly explains userId semantics (null means unassign), but nodeId and requestId are left implicit — the description does not state which ID identifies the capture request versus the landscape node. This leaves a meaningful gap for a 3-parameter tool with no schema descriptions.

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

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

The description names a specific action (assign/unassign), a specific resource (open Process Landscape capture request), and the target (team member). It also explicitly distinguishes unassignment via userId: null, which differentiates it from sibling tools like assignClarityExtraCaptureRequest or assignClarityLandscapeNodeTeam.

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

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

The description gives clear context for when the tool applies: the capture request must be open, the caller should be manager+, and unassignment is done by passing userId: null. It does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

The description discloses the side effects of moving captures and briefs, and explains the special behavior when intent is 'accept-proposal'. It also notes that null team is rejected. This aligns with the idempotent and non-destructive annotations without contradiction.

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

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

The description is concise and well-structured, fitting two sentences without unnecessary detail. It front-loads the core action and then elaborates with conditional behavior, 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 provides enough context to call the tool correctly for both proposed and existing nodes, and mentions the moving of captures and briefs. The absence of an output schema is acceptable, and the behavioral nuances are covered. Minor lack of explicit 'when not to use' is not critical.

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 descriptions for intent, nodeId, and teamId, clarifying their roles and constraints. The orgId lacks a description, but its purpose is inferable. The tool description reinforces parameter behavior but doesn't add significant new 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 clearly states the tool's primary action ('Set the owning team of a process in the process landscape') and distinguishes behavior for proposed vs. existing processes. It also notes the admin permission requirement, which helps agents understand scope.

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

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

The description implicitly guides usage by explaining what happens in each scenario (accepting a proposal vs. moving an existing process). However, it does not explicitly contrast with sibling tools or state when to choose this over alternatives like acceptClarityLandscapeNode.

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 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?

Annotations are all false, so they convey only that this is a mutating, non-idempotent, non-destructive operation in a closed world. The description adds meaningful behavioral context beyond that: the queue and Case will 'share one document' and 'a later change moves them together,' plus the precondition that the queue must not already have a schema. It does not mention failure behavior if the precondition is violated.

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

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

Two sentences with no filler. The core action is front-loaded, the consequence is explained, and the precondition is delivered in the second sentence. Every word earns its place.

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

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

The conceptual model and precondition are covered, and there is no output schema to document. The main gap is that family_id — one of only two required parameters — is undefined in both the schema and the description, which an agent needs to call the tool correctly. The relationship to createQueueJsonSchema is also left implicit rather than explicit.

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%: queue_id is described in the schema but family_id has no description. The tool description does not compensate — it never explains what family_id refers to (presumably the Case schema family), leaving half the required parameters semantically ambiguous for the agent.

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: 'Put a queue on an existing Case schema.' It further explains the resulting shared-document behavior, which distinguishes this from siblings like createQueueJsonSchema (new schema) and detachQueueJsonSchema (remove attachment) without needing to open their schemas.

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

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

The phrase 'existing Case schema' establishes the context: use this when a Case schema already exists and a queue needs to be joined to it, as opposed to creating a fresh schema. It also states the precondition 'The queue must not already have a schema.' However, it does not explicitly name alternatives or say when not to use it.

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

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

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 indicate non-read-only and non-idempotent behavior, and the description adds valuable context: email entries can create invitations, and each node-person outcome can report success, conflict, or delivery failure. This goes beyond the annotations by revealing side effects and per-item status granularity.

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 the action and scope front-loaded, followed by the most important behavioral outcomes. Every sentence contributes information, and there is no redundant or vague 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 mutating batch tool with no output schema and no field-level descriptions, the description covers the core action, bounded scope, invitation side effect, and outcome categories. However, it lacks explicit guidance on choosing this over the singular sibling, does not mention prerequisites or permission needs, and does not describe the expected response structure for the reported outcomes.

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

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

With schema description coverage at 0%, the description needed to compensate, but it only glosses over parameters as 'people' and 'Process Landscape nodes' and adds that email entries can create invitations. It does not explain the meaning of processRole, teamRole, or the relationship between nodeIds and people beyond the schema's raw names and 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?

The description states a specific verb, resource, and scope: 'Add one or more people to multiple Process Landscape nodes in a bounded batch.' It also distinguishes itself from the singular sibling addClarityLandscapeNodePerson by emphasizing the multi-node batch nature and mentions the invitation side effect.

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 batch usage across multiple nodes and mentions boundedness, but it does not explicitly state when to use this tool versus addClarityLandscapeNodePerson or any alternatives. There are no exclusion criteria, prerequisites, or direct sibling comparisons, so the agent must infer the appropriate choice from the tool name and phrasing.

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?

The description adds meaningful behavioral context beyond the annotations: active runs are interrupted first, cases are reset to pending, and assignment happens on the next dispatcher tick. This is particularly valuable because the annotations do not convey these side effects, and the destructiveHint=false does not preclude run interruption.

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 convey the action, the side effects, and the prerequisite with no filler. The most important scoping information is front-loaded, and 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?

The description covers the core lifecycle and the key prerequisite for successful invocation. Given the nested filters and selection parameters, the schema carries the parameter details, and the description supplies the operational context that schema cannot. It does not explain return values, but for a bulk action with no output schema, the behavioral flow is the more important context.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description does not add much parameter-level meaning beyond the overall lifecycle, such as guidance on choosing between case_ids and all_matching. It stays at the baseline appropriate for full schema coverage.

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

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

The description opens with a specific verb and resource: 'Re-process multiple cases on a chosen agent.' It further clarifies the behavior by describing the reset and reassignment lifecycle, which distinguishes it from sibling tools like bulkUpdateCaseStatus or startRun.

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

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

The description provides a clear operational context and a concrete precondition: the chosen agent must already be connected to the queue as a case-queue-consumer with the trigger enabled or disabled. It does not explicitly contrast with alternatives, but the precondition and lifecycle detail give sufficient guidance for appropriate use.

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

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

The description goes well beyond the annotations by explaining the semantics of priority ordering, noting that due postponed cases are handled first and higher priority follows. It also discloses non-side-effects and documents the effect of setting priority to 'none', which is exactly the behavioral context an agent 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 description is four compact sentences that front-load the action, then efficiently cover ordering semantics, non-effects, and the clearing behavior. There is no filler, repetition, or unnecessary restating of schema property names.

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 behavioral and side-effect profile is well covered, and the schema fully documents parameters. However, the description does not address the selection-mode constraint between explicit case_ids and all_matching/filters, nor does it mention prerequisites like queue existence, so the agent must rely on the schema for these invocation details.

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

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

Schema description coverage is 100%, so the baseline is 3 because the schema already documents all six parameters. The description adds only marginal value by explaining the default-clearing behavior of 'none', but it does not meaningfully clarify search, filters, case_ids, or all_matching beyond the schema.

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

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

The description opens with a specific verb and resource: 'Set the priority of multiple cases.' It also differentiates itself from sibling tools by emphasizing the bulk scope and by explicitly stating that it never changes case status, separating it from bulkUpdateCaseStatus.

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

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

The description provides clear context for when this tool is relevant: priority only affects the order pending cases are picked up, and it explicitly excludes side effects like interrupting runs or changing status. It does not name alternative tools such as bulkUpdateCaseStatus, so it stops short of full alternative routing.

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

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

With all annotations false, the description carries the full disclosure burden and meets it thoroughly: it reveals that the call interrupts active runs, releases case ownership, preserves human-in-the-loop state (pending requests and approval batches stay answerable), and re-dispatches cases when resetting to pending. This is exactly the kind of side-effect context an agent needs and it does not contradict any annotation.

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 dense, front-loaded sentences: core action first, then side effects, then the pending-specific consequence. Every sentence earns its place, and none repeats information already present in the annotations or schema.

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

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

For a 6-parameter bulk mutation with nested filters and no output schema, the description plus the fully-covered schema give an agent almost everything needed: selection semantics, status semantics, and non-obvious side effects are all disclosed. The only gap is the return value/confirmation shape, which neither the description nor an output schema addresses.

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 status semantics (terminal states, 'success' not settable, pending reset) and selection semantics (case_ids vs all_matching). The description's only additive parameter insight is the trigger-consumer re-dispatch detail for pending, which is a marginal complement to the schema's 'pending resets the case'.

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

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

States a specific verb+resource ('Update the status of multiple cases') and enumerates the four settable target states (pending, completed, failed, canceled). This clearly distinguishes it from sibling tools like bulkUpdateCasePriority (priority) and bulkReprocessCases (reprocessing) without needing to inspect their schemas.

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

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

The bulk status-update context is clear and the behavioral consequences are spelled out, but the description never names alternatives (e.g., updateCase for single-case updates, bulkUpdateCasePriority for priorities) or states explicit when-not-to-use conditions. Usage is implied rather than directive.

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?

Beyond the annotations, the description discloses two meaningful side effects: the suggestion's change is staged into the Agent's draft revision, and pending suggestions made moot are auto-cleared. This is valuable behavioral context that complements the non-readonly annotation without contradicting it.

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

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

The description is a single efficient sentence that front-loads the core action and includes the most important side effect. Every word earns its place with no filler or redundancy.

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

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

For a mutating action with no output schema, the description captures the essential behavior: applying, staging into a draft, and clearing moot suggestions. It could mention what happens to the applied suggestion itself or failure conditions, but the core calling context is sufficiently clear.

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 revision_id and create_new_draft lacking descriptions, and the tool description does not directly explain those parameters. However, the phrase 'Agent's draft revision' provides useful context for understanding revision-related fields, and selected_automation_revision_id already has a thorough schema 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 states a clear verb and resource: 'Apply a suggestion' and then explains the exact mechanism — staging the change into the Agent's draft revision and auto-clearing moot suggestions. This is specific enough to distinguish it from rejectAgentSuggestion and the Clarity-focused accept/dismiss suggestion tools.

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

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

The primary usage is implied by the verb 'Apply' — use this tool when you want to accept an agent suggestion — but it never explicitly contrasts with rejectAgentSuggestion or other accept variants. There is no stated when-not-to-use guidance or prerequisite such as 'only after reviewing via getAgentSuggestion'.

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 a mutating, non-idempotent operation (readOnlyHint=false, idempotentHint=false), and 'Create' is fully consistent with them — no contradiction. The description adds one genuine side-effect disclosure: passing a build creates the first build in the same request. Other behavioral traits, such as automation_id's note that an automation is auto-created when omitted and type being fixed at creation, live in the schema rather than the description, leaving the description itself thin on behavior.

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

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

Two sentences totaling roughly twenty words, with the core purpose front-loaded in sentence one and the optional capability in sentence two. There is no filler, no repetition of the title or schema, and every word earns its place. This is a model of compact description writing.

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

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

Despite high complexity — 7 parameters with deeply nested build/config/data objects — the schema comprehensively documents every level, including side effects and alternative routes (code-step builds routed to revisions, team_id key-pinning rules for API vs OAuth callers). The main description is brief, but the definition as a whole equips an agent to select and invoke the tool correctly. The absence of an output schema and any hint of what the create response returns keeps this from 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 baseline of 3 applies, and the schema is unusually rich: files distinguishes path from GCS id, agent model conditions on the team's oss_models flag, plugins distinguishes built-ins from GitHub URLs, and subAgents documents its own retirement. The main description contributes only marginal parameter context ('Optionally include a build configuration'), which merely echoes the schema's own detailed build documentation. The schema carries the load here.

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 'Create a new agent,' a specific verb+resource that clearly matches the tool name and sets it apart from narrow siblings like createAgentCaseTrigger, createAgentFolder, and createAgentSlackTrigger. The second sentence adds real scope detail (optional inline build), clarifying this is the full agent-creation entry point. It stops short of a 5 because it never explicitly names what it is not, such as duplicateAgent or the code-step revision path.

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 top-level description only implies when to use the tool (whenever a new agent is needed) and gives no explicit alternatives or exclusions. The strongest guidance is embedded in the schema: the build.config description explicitly says code steps' first builds must go through POST /v2/agents/{agent_id}/revisions, and the type description warns the step flavor is fixed at creation. There is no routing guidance against related tools like updateAgent or duplicateAgent, so guidance is partial rather than complete.

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?

Even with annotations already indicating this is a mutating, non-idempotent operation, the description adds substantial behavioral disclosure: the first agent is auto-created, the revision/draft lifecycle is explained, the default build is bound into the draft, first activation promotes to revision 1, and non-revision teams get a bare container. This is exactly the kind of side-effect detail that agents cannot infer from annotations.

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

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

Two sentences carry the core action up front and then pack necessary behavioral nuance into a dense but efficient second sentence. There is no filler, and the conditional structure clearly separates revision-semantics teams from all others.

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 is behaviorally complete for the two team scenarios and covers the side effects of creation. It does not mention what the caller receives back (e.g., the created automation's ID), which would be helpful given there is no output schema, but the schema and annotations cover most remaining operational needs.

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

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

Schema description coverage is 100%, with both name and team_id already well documented in the input schema. The tool description adds 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 opens with a specific verb and resource ('Create a new automation') and adds that the first agent is created alongside it, which clearly distinguishes it from related create tools like createAgent. The added behavioral detail makes the tool's purpose unmistakable even among a large sibling set.

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

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

The description provides rich context about how the tool behaves on teams with revision semantics versus other teams, which helps a caller set expectations. However, it never explicitly names alternatives such as createAgent for standalone agent creation or updateAutomation for modifying an existing automation, so when-to-use versus alternatives is only implied.

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

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

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 provide only false/non-informative hints, so the description carries the full burden. It discloses meaningful behavioral detail: rubrics attach to the current version/build-set, the 409 precondition, and the 12-rubric cap. This is exactly the kind of context an agent needs beyond the schema.

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

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

The first sentence front-loads the core purpose, and the second sentence earns its place by defining case-level evaluation. The third sentence is dense, packing versioning, the 409 condition, and the 12-rubric limit into one clause, but it remains informative and reasonably sized for the complexity.

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 no output schema and non-informative annotations, the description gives enough context to invoke the tool correctly: the target version, the prerequisite, the failure mode, and the maximum rubric count. The only minor weakness is the slightly ambiguous phrasing around the 12-rubric condition, but it does not block correct 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 baseline is 3, but the description adds semantic value beyond the schema by explaining that rubrics are Pass/Fail questions evaluated at settlement across the whole case. This helps the agent understand what the title and description parameters should contain, even though the schema already documents their basic format.

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: 'Add one case-level evaluation rubric to a queue's current rubric set.' It clarifies what makes this rubric distinct ('judge the whole case across every Run that touched it') and distinguishes it from siblings like createEvalRubric and replaceCaseQueueEvalRubrics.

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

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

The description gives clear usage context: this adds a single rubric to the current build-set, only works after the first Agent-processed case settles, and fails with 409 before then. It does not explicitly name alternative tools such as replaceCaseQueueEvalRubrics, but the additive scope and constraints make the intended use reasonably 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 sparse annotations, it discloses the 400 error when both forms are provided, auto-creation of missing labels on the queue, and precise priority-ordering semantics. This is substantial behavioral information not inferable from 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?

The core purpose is front-loaded, and every sentence carries meaningful usage or behavioral information. There is no filler, redundancy, or vague phrasing.

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?

Input behavior is thoroughly covered, including parameter interaction and side effects. Since there is no output schema, the description's only notable gap is that it doesn't specify what the tool returns on success, such as created case IDs.

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

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

With low schema coverage, the description compensates by explaining the `case` vs `cases` relationship, title max length, free-form `data`, label creation behavior, and the priority enum. It also adds the mutual-exclusion error condition not present in the schema.

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

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

The description states the exact operation and target: 'Create one or more cases in a queue.' It clearly distinguishes single and bulk creation modes and reads unambiguously against sibling tools like updateCase or assignCaseLabels.

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 provides concrete invocation guidance: use either a single `case` object or a `cases` array, never both, with a 1-100 limit. It doesn't explicitly name alternatives such as `updateCase` or `assignCaseLabels`, so it has clear context but no exclusions.

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

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

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 indicate this is a mutating, non-read-only, non-idempotent operation. The description adds useful context about direct GCS upload and supported file types, but it does not disclose the full upload flow or side effects beyond signed URL creation.

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 with no filler. It efficiently communicates the action, supported formats, and destination while leaving schema details to the schema.

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

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

Adequate for a straightforward signed-URL generation tool, and the lack of an output schema is partly mitigated by the description implying the returned artifact is a URL. However, it omits the relationship to the completion step and does not distinguish this endpoint from several closely related upload-URL siblings.

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 parameter descriptions already provide clear meanings for id, fileName, contentType, and extraCaptureRequestId. The description reinforces the document-upload purpose but adds no additional semantics beyond the schema.

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

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

States a specific action (create a signed URL) and resource (Clarity document upload to GCS), and lists the supported formats. It distinguishes from image/video upload tools via the format list, but does not differentiate among closely related document-upload siblings such as organization, team, or artifact uploads.

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

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

No guidance on when to use this tool versus sibling upload tools like createClarityOrganizationDocumentUploadUrl or createClarityTeamDocumentUploadUrl. It also does not mention follow-up steps such as completing the upload after GCS transfer.

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 provide only negative hints, so the description carries the behavioral burden. It discloses that the tool only creates a signed URL rather than performing the upload, and that uploads happen directly to GCS. This is meaningful beyond the structured fields, though it does not mention expiration or follow-up completion steps.

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 provides the essential action, target, and constraints with no filler. Every word contributes to understanding what the tool does.

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 complete schema coverage, the description sufficiently conveys the outcome: a signed URL for direct image upload. It does not specify response shape or follow-up behavior, but the tool's purpose is clear enough 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?

All parameters are fully described in the schema, including the contentType enum and UUID formats. The description adds no extra parameter-level meaning, so the baseline score 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 names a specific action (create a signed URL), a specific target (GCS), and supported formats (PNG, JPEG, WebP). This clearly distinguishes it from sibling tools like createClarityDocumentUploadUrl 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?

The description makes the usage context clear: use this when an image needs to be uploaded directly to GCS via a signed URL. It does not explicitly name alternatives or exclusion conditions, but the format and storage constraints imply the right scenario.

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 mutating, non-idempotent operation. The description adds valuable behavioral detail by stating the authorization requirement and the side effect that 'creating a new link invalidates any prior active link for the process,' which an agent would not otherwise know.

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. It front-loads the primary purpose and immediately follows with the permission and side-effect information needed for correct use.

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

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

For a one-parameter tool with no output schema, the description covers the purpose, the authorization prerequisite, and the important invalidation side effect. Nothing needed to invoke the tool 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%, and the single parameter already has its own description ('The clarity process id'). The tool description adds no further parameter-level detail, 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 opens with 'Create or regenerate a process-scoped Clarity interview invite link', naming a specific verb and resource. The phrase 'interview invite link' distinguishes it from sibling link-creation tools such as createClarityProcessLink and createTeamInviteLink.

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 provides clear usage context by specifying the permission boundary: 'Only the process creator or team managers can create invite links.' It also explains the regenerate behavior, but it does not explicitly name an alternative tool or state when to prefer this one over a sibling such as createClarityProcessLink.

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

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

The description adds useful context beyond the sparse annotations by disclosing that active areas require organization admin+ while proposals are open to any member. However, it does not disclose side effects, return behavior, or the idempotency nuance described in the creationMode schema.

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

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

The description is a single, front-loaded sentence with no filler. It packs the core purpose and key permission distinction into minimal space.

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

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

With six parameters, no output schema, and weak annotations, the description is too thin to be complete. It lacks guidance on parent/owner fields, sibling alternatives, and what the tool returns or how creation is confirmed.

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 description partially compensates for the low 33% schema coverage by explaining the creationMode distinction and its permission implications. However, it adds no meaning for parentId or ownerLabel, and name/orgId remain only schema-defined, so the description does not fully carry the parameter-semantics burden.

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

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

The description clearly states a specific verb ('Create'), resource ('area folder'), and location ('in the process tree'), which distinguishes it from sibling tools like createClarityFolder or createClarityProcessNode. It does not explicitly name a sibling, so it stops short of the clearest possible differentiation.

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

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

The description gives a permission-based distinction between 'active' and 'proposal' areas but does not explain when to prefer this tool over alternatives such as createClarityFolder or updateClarityLandscapeNode. No explicit when-to-use or when-not-to-use 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 declare readOnlyHint=false and destructiveHint=false, so the mutation-but-non-destructive nature is covered. The description adds the signed-URL semantics and upload-oriented behavior, but does not disclose details like URL expiration, single-use behavior, or the follow-up completion step.

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. Every word contributes to identifying the action, scope, and file types 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 simple 3-parameter URL creation tool with no output schema, the description is largely sufficient: it names the resource, scope, file types, and the upload purpose. It does not explicitly point to the paired completeClarityOrganizationDocumentUpload step or response shape, but 'signed URL' communicates the key output clearly.

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 67%, with orgId lacking a description, but the description adds meaningful semantic mapping: PDF/TXT/Markdown/BPMN maps to the contentType enum and 'organization-level' clarifies the role of orgId. This goes beyond what the raw schema provides.

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

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

The description states a specific verb ('Create'), a concrete resource ('signed URL'), and explicit scope ('organization-level Clarity capture'). It also enumerates supported file types, making it easy to distinguish from sibling tools like createClarityTeamDocumentUploadUrl and createClarityDocumentUploadUrl.

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 'organization-level' phrasing provides clear context about when this tool applies, distinguishing it from team- or artifact-scoped upload URL tools. However, it does not explicitly name alternatives or state when not to use it, leaving some inference to the 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?

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.

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

The description adds useful behavioral context beyond the annotations by specifying required permission (team manager or organization admin+) and clarifying the operation is about relocating an existing process into the landscape. It does not explicitly describe side effects on the Unsorted folder, but the wording implies filing/moving, and the annotations indicate a non-read-only, non-destructive mutation.

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

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

Two sentences, front-loaded with the primary action and immediately followed by the alternative-tool routing. There is no filler or redundant restating of the schema.

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

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

For a simple 3-parameter mutation tool, the description gives the action, the target context, permission requirements, and the key sibling distinction. It does not explain error cases or the exact return value, but those are not critical for an agent selecting and invoking this tool correctly.

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

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

The schema already documents parentId and processId well, and the description reinforces the processId semantics by tying it to processes in Unsorted. However, the description does not add much meaning for orgId, and schema coverage is only 67%, so the description only partially compensates for the 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 clearly states the action: file an existing Clarity process into an area of the process landscape. It also distinguishes this tool from proposeClarityLandscapeProcess, which creates a brand-new process, making the tool's purpose 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 gives the when-to-use condition: when the process already exists but sits in Unsorted. It also names the alternative tool for the opposing case. This is strong routing guidance 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?

The description adds context beyond the sparse annotations by clarifying that it creates a signed URL rather than performing the upload itself, and by listing allowed content types. However, it does not disclose URL expiration, side effects, or the need to follow up with completeClarityTeamDocumentUpload, which is significant since readOnlyHint=false indicates a potentially state-changing operation.

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

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

A single front-loaded sentence states the action, resource, supported formats, and scope with no redundant wording. It avoids repeating the title or parameter details while still conveying the core semantics.

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

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

For a low-complexity tool with full schema parameter coverage and clear file-type constraints, the description is nearly complete: it tells the agent what operation is performed and which document types qualify. It is slightly incomplete because there is no output schema and the description does not mention the upload-completion workflow or the shape of the returned signed URL.

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

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

Schema coverage is 100%, and the schema already provides a detailed team_id description covering API-key fallback and OAuth behavior. The description's file-type list aligns with the contentType enum but does not add significant meaning beyond the schema; the mapping from 'BPMN' to application/xml is only implicit.

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 action ('Create a signed URL'), a concrete resource ('team-level Clarity capture'), and lists the supported document types (PDF, TXT, Markdown, BPMN). This clearly distinguishes it from org-level or general document upload URL tools based on the team-level scope.

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

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

The description implies the appropriate context by specifying 'team-level,' and the schema's team_id description gives useful auth guidance (omit for API keys, pass for OAuth callers). However, it does not explicitly name sibling alternatives such as createClarityDocumentUploadUrl or createClarityOrganizationDocumentUploadUrl, nor does it 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.

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

The annotations only provide generic flags (readOnlyHint=false, destructiveHint=false) and do not explain the operation's nature. The description adds meaningful behavioral context: the tool does not upload the video itself but returns a signed URL, and the upload is performed directly to GCS. This helps the agent understand the expected flow, though expiration or lifecycle details are not disclosed.

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

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

The description is a single, focused sentence that states the core purpose and the key storage destination ('directly to GCS'). There is no filler, repetition, or unnecessary detail, making it easy for an agent to parse quickly.

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 four-parameter tool with no nested objects, the schema fully documents inputs and the description explains the output concept ('signed URL') and the storage target. The main missing piece is explicit guidance on the follow-up completion flow, but the description is complete enough to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with all four parameters already documented meaningfully in the schema (id, fileName, contentType, extraCaptureRequestId). The description does not add parameter-specific detail beyond referring to 'uploading a video file', which the schema already captures. A baseline score of 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description names a specific verb ('Create'), a specific resource ('a signed URL'), and a specific context ('uploading a video file directly to GCS'). This clearly distinguishes it from sibling upload-URL tools like createClarityImageUploadUrl, createClarityDocumentUploadUrl, and createFileUploadUrl without requiring the agent to inspect schemas.

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

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

The description implies the usage context: this is the URL-generation step before a video is uploaded directly to GCS, and the sibling completeClarityVideoUpload suggests a follow-up step. However, it does not explicitly say when to choose this over other upload-URL tools or mention the completion step, so the usage guidance remains implicit rather than explicit.

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

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

Annotations already establish that this is a non-read-only, non-idempotent mutation. The description adds useful context that the tool creates a custom MCP connection and that OAuth flows need different endpoints. It does not disclose side effects, failure behavior, or what happens when auth_method is set to oauth, but with annotations present this is a moderate level of transparency.

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

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

The description is two sentences with the core purpose front-loaded. The caveat about OAuth flows is placed immediately after the main statement, and the explicit endpoint paths add practical value without excessive verbosity.

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 8 parameters, a nested headers object, an auth_method enum that includes oauth, and no output schema, the description is not complete enough. It leaves unclear how auth_method interacts with the warning about OAuth flows, what server_url and headers mean for a custom MCP server, and what response or validation behavior to expect. The tool needs more behavioral and parameter context to be safely invoked.

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 13%, and the description provides almost no parameter-level guidance. It does not explain name, server_url, headers, auth_method, or custom_integration_id beyond what the bare schema types and enum imply. The team_id parameter is well described in the schema, but most required and optional parameters remain semantically opaque.

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

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

The description states a clear verb-resource pair: "Create a new user-provided connection (custom MCP server) for the current team." It names the resource type, the scope (team), and clarifies that this is specifically for custom MCP servers. It also explicitly contrasts with OAuth-based integrations, though it doesn't differentiate from closely named siblings like createCustomIntegration or createCredential.

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 tells agents when NOT to use this tool: OAuth-based integrations with an interactive browser flow should use the dedicated OAuth endpoints instead, and it names those endpoints. However, it doesn't provide guidance for choosing between this and other connection-related siblings such as createCredential, createCustomIntegration, or probeMcpServer.

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 establish that this is a mutating, non-idempotent operation. The description adds useful behavioral context: personal-by-default sharing behavior, the lead-builder role gate for shared logins, and the at-least-one validation constraint. These details go beyond what annotations alone reveal.

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

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

Three short sentences front-load the purpose, then state the required combination constraint and the shared-mode behavior/role requirement. Every sentence earns its place with no redundant wording.

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

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

The definition is minimally sufficient for a basic personal credential: required fields are visible in the schema, the validation rule is explicit, and the shared path is explained. However, with no output schema and no description of what userId/domain represent, the agent must infer important invocation details rather than being told them.

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

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

Schema description coverage is only 14%, so the description must carry param semantics. It explains shared, password, and otp_secret meaningfully, but leaves the required userId and domain parameters unexplained, and also doesn't clarify username. This is a partial compensation for a 7-parameter tool.

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

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

The description states a specific action and resource ('Create a login') and clarifies that a credential is a login rather than a generic secret or connection. It doesn't explicitly name a sibling alternative, but the resource type is specific enough to distinguish it from tools like createSecret or updateCredential.

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 parameter-level guidance: at least one of password or otp_secret is required, and shared: true is the switch for team-shared logins with a role requirement. However, it doesn't say when to prefer this tool over related alternatives like updateCredential or createSecret, so the tool-selection guidance is mostly implied.

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

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

Annotations already signal readOnly=false, idempotent=false, and destructive=false, so the write behavior is known. The description adds valuable behavioral context beyond annotations: the created entity is a team-level catalog entry, the operation requires manager-or-above permissions, and users will later connect it as an MCP connection. This is meaningful for an agent deciding whether to call the tool.

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

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

The description is a single, dense sentence with no filler or repetition. The verb and resource are front-loaded, and the role requirement is appended without bloating the text. Every part 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?

The description is sufficient to understand the high-level purpose and permission requirement, but it does not cover parameter dependencies such as when oauth_client_id and oauth_client_secret are needed, nor does it clarify the server_url/auth_method semantics. With no output schema and only 17% schema description coverage, the definition is minimally viable but has 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 only 17%, with team_id carrying the sole description. The tool description does not explain server_url, auth_method, oauth_client_id, oauth_client_secret, or how they relate to each other. Since the schema leaves most parameters undescribed, the description needed to compensate but does not.

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 specific resource ('custom integration type'), and adds a clarifying parenthetical ('team-level catalog entry') that distinguishes it from a concrete connection. The follow-up clause about users connecting them as user-provided MCP connections makes the tool's purpose unmistakable and separates it from sibling tools like createConnection.

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

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

The description gives clear context: this creates a reusable catalog entry rather than an actual connection, and it requires a manager-or-above role. It does not explicitly name alternatives or say 'when not to use', but the catalog-vs-connection framing provides enough guidance for an agent to select it appropriately.

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

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

The description adds meaningful behavioral context beyond the annotations: the 5-custom-rubric ceiling, the 409 failure mode, and the default live-build behavior. It does not contradict annotations, which already signal a non-read-only write; the more nuanced selected_automation_revision_id behavior is left to the schema.

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

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

Three short sentences front-load the core action, then state the most important constraint (5-rubric ceiling with 409) and the default targeting behavior. There is no filler, repetition, or unnecessary 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 5-parameter write tool with no output schema, the description covers the key failure mode and default target behavior, which is solid. It does not mention the success return value or summarize selected_automation_revision_id's draft/active/historic branching, but that parameter's behavior is fully documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3 even with no parameter enrichment in the description. The description does add default-build semantics for build_id, but this largely restates the schema. It does not meaningfully enrich title, agentId, description, or selected_automation_revision_id beyond what the schema already says.

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

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

The description names the specific verb and resource: 'Add one Agent-specific evaluation rubric to a build.' It distinguishes this tool from sibling queue-level rubric tools like createCaseQueueEvalRubric, and from replace/delete/update rubric tools, by specifying the Agent-specific build scope.

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

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

The description provides clear invocation context: it defaults to the Agent's live build and says to pass build_id to target a specific revision. It does not explicitly name alternatives or state when not to use this tool, but the Agent-specific build framing implies the intended situation.

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 some behavioral context beyond the annotations by indicating that this generates a signed URL for direct GCS upload, implying the actual file transfer happens client-side. However, it does not disclose URL expiry, required permissions, or what happens after generation. Annotations are not contradicted.

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. 'Generate a signed URL' appears first, followed by the purpose qualifier 'for uploading a file directly to GCS,' and every word earns its place.

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

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

The tool is simple and the schema fully documents all parameters, so the description is mostly adequate for invoking it. However, the large sibling set creates ambiguity about when this generic upload URL tool should be chosen over domain-specific ones, and the absence of an output schema leaves return-value details unstated.

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 parameters fileName, contentType, and team_id are already fully documented in structured form. The description contributes no additional parameter-level meaning beyond referring to 'a file.'

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: generate a signed URL for uploading a file directly to GCS. It is clear about what the tool does, though it does not distinguish itself from the many sibling create*UploadUrl tools.

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

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

No guidance is provided about when to use this tool versus alternatives like createCaseAttachmentUploadUrl, createClarityDocumentUploadUrl, or createSandboxUploadUrl. The description gives context but no explicit or implicit selection criteria beyond 'file directly to GCS.'

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