Duvo MCP

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

Annotations already declare the tool is not read-only, not idempotent, and not destructive. The description adds behavioral context by stating it 'creates the durable capture request' and implies the suggestion is consumed (accepted). It also discloses an authorization requirement ('manager+'). This goes beyond what annotations provide, though it could mention side effects like approval workflows.

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 of 15 words, no filler or redundancy. It front-loads the action and resource, making it quick for an agent to parse. Every word contributes to the meaning.

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

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

Given the tool's simplicity (2 params, no output schema, no enums), the description is adequate for basic invocation but lacks parameter semantics and any mention of return values or side effects. It does not cover what happens after acceptance (e.g., notifications, state changes). The agent may need to infer from context or previous interactions.

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 has 0% description coverage—neither 'nodeId' nor 'suggestionId' are explained. The description hints that 'suggestionId' relates to the capture suggestion and 'nodeId' is likely the landscape node, but it does not explicitly define their roles or constraints. The description should compensate for the missing schema descriptions but falls short.

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 ('Accept'), the resource ('pending Process Landscape capture suggestion'), and the outcome ('create the durable capture request'). It distinguishes itself from sibling tools like dismissClarityCaptureSuggestion and acceptClarityLandscapeNode by specifying the exact type of suggestion and the resulting durable request.

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 identifies the context—pending landscape capture suggestions—and includes a role constraint ('manager+'), but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., acceptClarityTeamAssignmentSuggestion) or exclude cases (e.g., when to dismiss instead). The usage is clear but not deeply instructional.

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 that this is a state-changing mutation (accepting a proposal), not destructive (re-accepting is a no-op), and requires admin privileges. Annotations already indicate destructiveHint=false, but the description adds context about authorization and the no-op behavior, which are valuable beyond the structured fields.

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

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

Three concise sentences front-loaded with the core purpose, followed by a clear exclusion and an edge case. No unnecessary words or repetition. 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 essential behavior, usage boundaries, and a key edge case. With only 2 parameters, no output schema, and basic annotations, this is largely complete. It does not explain return values or error handling, but for a simple acceptance action, the description provides sufficient context for an agent 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 coverage is 50% (only nodeId has a description). The tool description adds meaning by clarifying that nodeId is the proposed area folder, and the overall context explains orgId is the organization (via 'organization admin+'). However, orgId is not explicitly described in the tool description, leaving a slight gap. Still, it adds value 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 verb 'Accept', the resource 'proposed area folder', and the outcome: it stops being a proposal and becomes part of the real structure. It also distinguishes from the sibling tool 'assignClarityLandscapeNodeTeam' by specifying that only area folders are accepted via this tool, while processes go through the other.

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

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

Explicitly states when to use this tool (only for area folders) and when not to use it (proposed processes use assignClarityLandscapeNodeTeam instead). Also mentions the authorization requirement ('organization admin+') and the edge case that re-accepting an already-active area is a no-op, providing clear usage boundaries.

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 set destructiveHint to false, so this is not destructive. The description does not contradict annotations. It adds that the action grants 'process access', which is useful but vague. It does not disclose if the action is reversible, if it sends notifications, or if it replaces existing memberships. With no output schema, it carries some burden but is not severely lacking.

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 extremely concise: one sentence of 10 words. It front-loads the action and purpose with no filler. Every word adds value given the simple tool with one parameter.

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 only one parameter, no output schema, and a straightforward action, the description covers the basic purpose but lacks details about what 'process access' entails, error scenarios (e.g., expired or invalid token), and the resulting state. Sibling tools suggest related workflows (getClarityProcessJoinInfo, createClarityInviteLink) that the agent might need before using this tool, but the description does not hint at these dependencies.

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 has one required parameter, 'token', with no description. Schema description coverage is 0%, so the description should compensate. The description mentions 'invite link' but does not clarify that the 'token' parameter is the extracted token from that link, nor does it describe the token format or source. This leaves the agent with ambiguity about how to obtain the token.

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 specific verbs and resources: 'Accept a clarity interview invite link' and 'gain process access'. It clearly distinguishes the purpose from sibling tools like createClarityInviteLink or deleteClarityProcessInviteLink. However, it could be slightly more precise about what 'process access' entails.

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 any guidance on when to use this tool versus alternatives such as createClarityProcessInviteLink, getClarityProcessJoinInfo, or acceptClarityLandscapeNode. It does not mention prerequisites (e.g., having a valid invite link), nor does it indicate that the user must be the intended recipient.

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 no behavioral hints (readOnlyHint false, idempotentHint false, destructiveHint false). Description says 'durably assign' but omits side effects, authorization needs, reversibility, or whether it overwrites existing assignments.

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 sentence with 17 words, front-loaded with purpose. However, it could be slightly more structured without adding significant length (e.g., listing parameters).

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

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

With no output schema and minimal annotations, the description leaves major gaps: what happens after acceptance, meaning of 'manager+', return value, and prerequisites. A mutation tool requires richer context.

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

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

Schema coverage is 0% and description does not mention either nodeId or suggestionId, failing to clarify their roles or constraints beyond the schema's empty format definitions.

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?

Description uses specific verb 'accept' and resources 'pending Process Landscape team-assignment suggestion', clearly distinguishing from siblings like dismissClarityTeamAssignmentSuggestion or acceptClarityCaptureSuggestion.

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

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

Implies the tool is for pending suggestions but does not explicitly mention when to use accept vs dismiss or other alternatives, nor does it state preconditions like 'only if suggestion exists'.

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-readonly, non-destructive, non-idempotent. The description adds critical behavioral detail: supplying an email gives process access and sends an invitation—a side effect not covered by annotations. Does not mention idempotency 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?

Two sentences: first clearly states purpose, second adds essential behavioral nuance. No redundant or filler content. Every sentence contributes value.

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

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

Covers core action and the email side effect, but lacks information on return value, failure scenarios, or guidance on optional parameter combinations. With no output schema, the agent is left guessing what the tool returns or if it succeeds.

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 14% (only nodeId has a description). The description clarifies the crucial name vs email distinction, but provides no additional meaning for role, teamId, teamRole, leaving their purpose ambiguous. Partial compensation for low schema coverage.

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

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

The description clearly states the tool adds a person to a process landscape node, using the verb 'Add'. It distinguishes the core action from siblings like batchAdd or remove/update, though it does not explicitly name 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?

Provides explicit guidance on when to use name vs email, warning that email triggers an invitation and access grant. No mention of when to prefer batchAdd or update over this single-person add, which would improve differentiation.

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, idempotentHint=false, and destructiveHint=false, so the mutating nature is known. The description adds behavioral transparency by stating that the run is paused and will be resumed upon answering, and it discloses the authorization boundary ('creator or team editors'). 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 concise, just two sentences, and front-loads the core purpose. It efficiently conveys the action, permission, and the source for the critical toolCallId parameter without any 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 the tool's purpose and workflow well but is incomplete regarding parameter semantics. The answers object format and artifactId are essential for correct invocation, and with no output schema and no param descriptions, the description leaves these ambiguous. The permission note and toolCallId hint are helpful, but the tool is more complex than the description acknowledges.

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 has three required parameters (artifactId, toolCallId, answers) with zero description coverage. The description only explains how to find toolCallId, leaving artifactId and the structure/meaning of the answers object entirely unspecified. With such low schema coverage, the description needed to compensate but did 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 clearly specifies the action ('Answer a pending question'), the resource ('the Duvo Pulse agent'), and the effect ('resume the paused run'). It also distinguishes the tool from siblings like sendPulseDashboardMessage and stopPulseDashboardMessage by focusing on answering agent questions, and includes the permission context ('creator or team editors').

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

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

The description provides clear usage context: it is for pending questions from the Duvo Pulse agent and explains that the run will resume. It gives a concrete source for the required toolCallId ('from the dashboard's message transcript'). However, it does not explicitly state when not to use this tool or mention alternative tools, so it lacks explicit exclusions.

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

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

With annotations already indicating a non-read-only, non-destructive, non-idempotent operation, the description adds valuable context by disclosing that labels are auto-created on the queue if they don't exist. This goes beyond the annotation flags and clarifies the mutational side effect.

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

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

The description is two short, front-loaded sentences with no redundancy. It conveys the core action and a critical side effect without 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 moderate-complexity mutation tool with no output schema and helpful annotations, the description covers the primary behavior and the most important side effect. It doesn't mention behavior on existing labels or return value, but these are not critical given the annotations and schema richness.

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% (case_id and queue_id are described). The labels parameter lacks a description, and the tool description does not explain the key/value structure or limits. The description does reinforce the 'one or more' requirement, aligning with the schema's minItems, but adds minimal 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 uses a specific verb 'assign' and identifies the resource (labels on a case). It also clarifies a key side effect (creating labels on the queue), which distinguishes it from sibling tools like unlinkCaseLabels or createQueueLabel.

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 use case (assign labels to a case) but does not explicitly state when to use this tool over alternatives. No when-not conditions or alternative tool references are provided, leaving the agent to infer from the verb and context.

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

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

Beyond annotations, the description adds the auth restriction ('Restricted to admins and managers') and clarifies the unassignment behavior. No contradiction with annotations. It does not detail side effects or return behavior, but is transparent about the main operation.

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

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

The description is a single, front-loaded sentence that efficiently covers the action, unassignment option, and access restriction. No wasted words, clear and direct.

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 (4 required params, no output schema), the description covers the core operation, unassignment, and auth. It does not describe return values or side effects, but these are not critical for a straightforward assignment tool.

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

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

Schema description coverage is 100%, so parameters are already documented. The description repeats the null assignment behavior for user_id, which is already in the schema, adding no new semantic value. 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 states the action (assign/unassign), the target (team member), and the resource (extra-capture request). It distinguishes from siblings like assignClarityLandscapeCaptureRequest by specifying 'extra-capture request'.

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

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

The description implies usage for extra-capture requests and mentions unassignment with null, but does not explicitly differentiate from sibling tools or provide when-not-to-use guidance. The context is 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?

The description discloses the mutating nature (assign/unassign) and adds context beyond annotations by revealing role restrictions (manager+ for unassign) and the null userId unassignment pattern. No contradiction with annotations. It doesn't detail side effects or reversibility, but the tool is simple and the description covers key behavioral traits.

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

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

The description is a single sentence that front-loads the verb and resource, includes the unassign pattern, and has zero waste. It is concise while covering the core purpose and key usage nuance.

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 without output schema, the description covers the primary behavior and unassign pattern. However, it omits preconditions (e.g., what happens if the request is not open), error states, and the meaning of nodeId and requestId. It is minimally complete but has gaps that could confuse an agent in edge cases.

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

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

Schema coverage is 0% and the description does not explain the meaning of nodeId or requestId. It only adds value for the userId parameter by specifying that null unassigns. This is insufficient given the low coverage; the agent must guess what nodeId and requestId refer to from context.

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 (assign/unassign) and the specific resource (Process Landscape capture request), and distinguishes from sibling assignment tools by naming the resource explicitly. It also includes the special unassign behavior with 'userId: null'.

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 when-to-use context: assign an open capture request to a team member, or unassign by sending null. It implies the requirement that the tool is for open requests and that unassignment is manager+ only. However, it does not explicitly differentiate from similar sibling tools like assignClarityExtraCaptureRequest or mention 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?

Discloses behavioral traits beyond annotations: effect on proposed processes (accepts proposal and creates real process), effect on existing processes (moves process, captures, brief). Consistent with idempotentHint=true and destructiveHint=false, and adds side-effect details not captured in structured fields.

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

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

Two sentences, front-loaded with primary purpose, then nuanced scenarios. Every sentence adds value; no wasted words or redundant 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?

Tool has 4 parameters, no output schema. Description covers permission hint (org admin+), behavioral nuance, and associated resources. Minor omission: schema indicates teamId with null is rejected, but description does not mention this. Overall very complete for the complexity level.

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

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

Schema description coverage is 75% (3 of 4 params have descriptions). Description adds minimal extra meaning beyond the schema; it references 'proposed process' and 'existing process' which align with the intent enum, but the schema's own descriptions already convey that. No significant param insights beyond what 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?

Description specifies the verb 'set' and resource 'owning team of a process in the process landscape', clearly distinguishing between proposed and existing processes. This differentiates from siblings like acceptClarityLandscapeNode or assignClarityProcessLabels by focusing on the team assignment action.

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 on when to use: for assigning a team, with explicit scenarios for proposed processes (accept proposal) and existing processes (move). Though it does not explicitly mention alternatives or when not to use, the two scenarios provide strong usage 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 mutation (readOnlyHint: false) and no destructive behavior. The description adds 'assign' as a write action, but does not disclose whether assignments are appended or replaced, or whether labels can be created inline. It provides minimal additional behavioral context beyond the annotations.

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

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

The description is a single short sentence, making it concise and front-loaded. However, it is under-specified and omits important details about parameters and behavior, so it is not effectively structured for an agent to 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?

With no output schema and zero schema description coverage, the description must explain the full operation. It does not mention that there are two ways to assign labels (inline creation vs. existing IDs), nor what happens to existing labels on the process. The description is incomplete for a tool with this complexity.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only mentions 'process tags', which vaguely maps to labels, but provides no detail on the 'id' parameter (the process identifier), nor the difference between 'labels' (creating new inline) and 'labelIds' (referencing existing). The description fails to compensate for the schema's lack of explanatory text.

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 resource ('process tags' / 'process'), clearly indicating it attaches labels to a process. It distinguishes itself from sibling tools like createClarityProcessLabel or unlinkClarityProcessLabels, though the term 'tags' instead of 'labels' introduces slight ambiguity.

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

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

There is no guidance on when to use this tool versus alternatives such as createClarityProcessLabel (creating label definitions) or unlinkClarityProcessLabels (removing assignments). The description does not mention the two input modes (inline labels vs. existing label IDs) or prerequisites like having the process ID.

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

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

Annotations already indicate a non-read-only, non-idempotent, non-destructive operation. The description adds useful behavioral context: it's for making tools available and is creator-only, which implies permission requirements. No contradictions 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?

Single sentence, front-loaded with the action, and includes only necessary details (purpose, restriction). No wasted words.

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

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

For a simple two-parameter tool with annotations and no output schema, the description covers the core behavior, purpose, and a key restriction. It doesn't mention edge cases like re-attaching or return values, but the low complexity doesn't demand more.

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 0%, so the description must compensate. It gives context by defining connections as 'data sources' and mentioning 'dashboard', which helps map connection_id to a connection and artifactId to a dashboard. However, it doesn't explicitly state which parameter is which, relying on parameter names.

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') and clearly identifies the resource ('connections (data sources)' to a 'Duvo Pulse dashboard'), plus the purpose ('so the agent can use its tools'). It distinguishes from sibling tools like detachPulseDashboardConnection and listPulseDashboardConnections.

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 clear context for use: attaching a connection to enable agent tools. Mentions a restriction ('creator only') but doesn't explicitly name alternative tools for when not to use it. The sibling detachPulseDashboardConnection implies a reverse operation, but no explicit when-not guidance is given.

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

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

Annotations already declare readOnlyHint=false, but the description adds critical operational behavior: for case-queue-producer and case-queue-consumer integrations, attaching alone is insufficient and will cause runtime failure unless queues are linked. It also recommends a confirmation step with getRevisionCaseQueueSetup. This far exceeds annotation coverage and gives actionable operational warnings.

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

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

The description is front-loaded with the primary purpose and then delivers precise, high-value warnings and follow-ups. Every sentence earns its place; the 'IMPORTANT' section is justified by the severity of the runtime failure it prevents. No fluff or repetition.

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

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

The tool has a complex integration semantics requiring warnings about special cases. The description fully covers the attach action, the pinning alternative, the queue-linking requirement, and a verification step. It is complete given the schema provides parameter details and no output schema is expected.

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 extra meaning for integration_ids by explaining that specific integration types (case-queue-producer and case-queue-consumer) have additional requirements beyond simply being in the list. This contextual parameter guidance justifies a score above baseline, though it doesn't detail every parameter.

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 the specific verb 'Attach' with a clear resource ('one or more integrations to an agent revision'). It explicitly distinguishes itself from related sibling tools by naming pinRevisionIntegrationConnection, replaceRevisionIntegrationQueues, and getRevisionCaseQueueSetup as separate follow-up actions.

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 explicit when-to-use guidance and names alternatives: 'To pin specific connections after attachment, use pinRevisionIntegrationConnection' and 'until you link at least one queue with replaceRevisionIntegrationQueues.' It also gives a verification step, making the usage context unmistakable.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description adds valuable context: the effect on Runs and permission constraints for personal vs. team-shared logins. This goes beyond the structured annotations without contradicting them.

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

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

Two sentences, no redundant wording. The first sentence states the core action and purpose, the second adds a necessary permission constraint. Every word earns its place.

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

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

For a simple attach operation with three UUID parameters and no output schema, the description covers purpose, usage, and permission context. It does not mention return values or error behavior, but given the annotations and simple nature, it is reasonably 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?

The schema has 0% description coverage and the description does not explain any of the three parameters (agentId, buildId, exposedCredentialId). 'Login' is not explicitly mapped to exposedCredentialId, leaving ambiguity. The description fails to compensate for the schema's lack of explanations.

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 a login to a revision' and explains the purpose ('so the agent can use it during Runs spawned from that revision'). This specifically distinguishes it from sibling tools like attachRevisionSecret or attachRevisionIntegrations, which target different resource types.

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 login needs to be attached to a revision for Runs. It also adds permission requirements (owner vs. builder). However, it does not explicitly reference alternatives or state when not to use it, though the purpose clarity largely covers this.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the agent knows this is a mutating, non-idempotent operation. The description adds useful context about permission constraints (owner vs. builder permissions), which is valuable beyond annotations. However, it doesn't disclose side effects like whether attaching is reversible or what happens on conflict.

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

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

The description is two sentences, front-loads the primary action, and adds permission context without fluff. 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, no annotations describing behavior beyond flags, and 0% parameter coverage, the description should explain more—such as what response to expect, whether multiple secrets can be attached, or what constitutes a valid credentialId. The permission note helps but is insufficient for a mutating tool with three required UUID parameters.

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

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

Schema description coverage is 0%, so the description carries the full burden, but it does not explain the roles of agentId, buildId, or credentialId beyond implying they identify the revision and secret. It doesn't clarify that credentialId likely refers to a secret's credential, or how the three parameters relate. This is a significant 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 tool attaches an env-var secret to a revision for key injection into Runs, which is a specific verb+resource+outcome. It differentiates from siblings like attachRevisionIntegrations and attachRevisionLogin by focusing on secrets, though it doesn't explicitly name them as 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?

The description implies usage context (when attaching secrets to revisions) and mentions permission requirements for personal vs. team-shared secrets, but it doesn't explicitly state when to use this tool versus alternatives or when not to use it. It provides some guidance but lacks explicit 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 the key behavioral flow: it returns an authorization URL that the user must open, and Duvo creates the connection after consent and redirects to returnUrl. This adds meaningful context beyond the sparse boolean annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), clarifying the multi-step, user-involving nature of the operation.

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

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

The description is two sentences, front-loaded with the main action and mechanism. Every phrase earns its place: initiating the flow, the DCR method, the authorization URL, the consent step, the connection creation, and the returnUrl redirect. No wasted words.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is somewhat brief, but the rich schema fills in the details (e.g., team_id, oauth_client_id, reconnect_instance_id). The description provides the essential conceptual model—OAuth with DCR and the browser-based consent flow—which is sufficient for an agent to understand the tool's role. It could potentially mention reconnection or catalog connections, but the schema covers those.

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 has 100% description coverage, so the baseline is 3. The description mentions returnUrl and its role in the redirect, but this largely reiterates the schema description ('Where to send the user's browser after consent completes'). It does not add new meaning or clarify any parameters beyond what the schema already 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 clearly states the tool's purpose: 'Start an OAuth-based connection with a remote MCP server using Dynamic Client Registration.' It uses a specific verb ('start'), identifies the resource ('remote MCP server'), and mentions the key mechanism (DCR), which distinguishes it from siblings like startNativeOAuth or 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 provides clear context for when to use the tool: for OAuth-based connections with a remote MCP server. It explains the flow (returns authorization URL, user grants consent, Duvo creates connection) but does not explicitly mention alternatives or when not to use it. The context is clear, though exclusions are absent.

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 mutability (readOnlyHint=false) and non-idempotency, but the description adds valuable context: 'Email entries can create invitations' and 'each node-person outcome reports success, conflict, or delivery failure'. This discloses side effects (invitation creation) and potential failure modes beyond what annotations convey.

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

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

Two concise sentences with no wasted words. The first sentence states the primary purpose and scope; the second adds behavioral nuance and outcome reporting. 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?

Given no output schema, the description appropriately mentions outcome reporting (success, conflict, delivery failure). The bounded batch hint aligns with schema constraints (maxItems 20). It covers inputs and key behavioral effects. Missing details about return format or idempotency are minor given the tool's batch nature and sibling context.

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

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

Schema coverage is 0%, so the description carries the burden. It adds one useful insight: 'Email entries can create invitations', which clarifies the email field's behavioral implication. However, it does not explain orgId, nodeIds, or the people subfields (name, processRole, teamRole). Parameter names are self-evident but the description could add value by detailing constraints or relationships.

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 one or more people'), the target ('multiple Process Landscape nodes'), and the scope ('bounded batch'). It also mentions outcome reporting, which distinguishes it from the singular sibling tool 'addClarityLandscapeNodePerson'. The verb+resource+scope is specific and unambiguous.

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

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

The description implies this tool is for batch operations across multiple nodes, but does not explicitly state when to use the singular alternative or when not to use this tool. The context of 'bounded batch' and listing multiple nodes provides clear usage context, but lacks explicit exclusions or alternatives.

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

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

The description claims the transformation_proposal_id is a 'durable idempotency key' that makes retries return the same run, implying idempotent behavior. However, the annotation explicitly sets idempotentHint=false, creating a direct contradiction. According to the rubric, this contradiction warrants a score of 1. The description does add value by disclosing async behavior and conflict responses, but the contradiction overrides.

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 extremely concise: three sentences, each with a clear purpose. The first sentence states the main action, the second explains idempotency and retry behavior, and the third describes return codes. No redundant or unnecessary information is present.

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

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

The description explains the initiation of an async workflow (202) and a conflict state (409), but does not cover what happens after the async run completes or how to retrieve results. Given that there is no output schema, the description could be more complete by mentioning potential success responses or follow-up actions. It is adequate for the triggering step but leaves the lifecycle partially open.

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?

While the input schema already provides 100% coverage with descriptions, the description adds significant behavioral semantics: it explains that transformation_proposal_id defaults to the process's live proposal and that it serves as an idempotency key. This extra context helps the agent understand the parameter's role beyond the schema's format and type 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 clearly states the verb and resource: 'Hand a transformation proposal for a v2 clarity process off to the workflow-builder pipeline.' It specifies two modes of operation (with or without transformation_proposal_id) and distinguishes this tool from siblings by its unique action of initiating an automation build, which no other sibling tool explicitly 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?

The description explains internal behavior (idempotency key, retry semantics, return codes) but does not provide any guidance on when to use this tool versus alternatives like proposeClarityLandscapeProcess or generateClarityProcessSnapshot. There is no explicit 'when to use' or 'when not to use' context, leaving the agent to infer usage from the tool 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?

The description discloses important behavioral details beyond annotations: immediate emailing, per-batch counts (succeeded/skipped/failed), rollback of failed invitations, and the server-configured 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, each carrying essential information: action and emailing, result categorization with rollback, and the accept-link caveat. 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?

Even without an output schema, the description covers the return shape (succeeded/skipped/failed counts), edge cases (skips, duplicate detection), and side effects (immediate email, rollback). Combined with the schema's thorough parameter descriptions, this is fully sufficient 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?

With 100% schema coverage, the schema already documents parameter types and constraints. The description adds useful context about batch result semantics (skip reasons, rollback) and reinforces that frontendUrl is ignored, enhancing understanding beyond the raw schema.

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

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

The description states a specific verb ('invite'), resource ('several people to a team'), and scope ('in one call'), clearly distinguishing the bulk tool from siblings like createTeamInvite (single invite) and createTeamInviteLink (link-based).

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 implies the intended use case—batch invitations—by emphasizing 'several people in one call' and describing per-batch results. However, it does not explicitly name alternatives or state when not to use this tool, like for a single invitation.

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 key behavioral traits: active runs are interrupted, cases are reset to pending and reassigned. This goes beyond the basic annotations (readOnlyHint=false, destructiveHint=false) by explaining the mutation's nature and side effects. It does not mention rate limits or error conditions, but the core behavior is well-covered.

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

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

The description is three sentences, front-loaded with the purpose, followed by key behavioral details and a prerequisite. Every sentence is essential and free of fluff. It is highly 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?

Given the tool's complexity (6 parameters, nested filters, two selection modes, no output schema), the description covers the core behavior and a prerequisite but omits mention of the two operational modes, batch limits (case_ids max 100), or error handling. It is sufficient for simple use cases but lacks completeness for a fully autonomous agent to use without schema inspection.

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

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

Input schema coverage is 100% with clear descriptions for all parameters. The tool description adds no additional parameter-level meaning—it mentions the 'chosen agent' but does not explain the two operational modes (case_ids vs. all_matching) or how filters work. The schema already handles parameter semantics, so the description's contribution is adequate but not enhanced.

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

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

The description clearly states the tool's purpose: 'Re-process multiple cases on a chosen agent.' It explains the specific steps (interrupt active runs, reset to pending, assign to agent) and distinguishes it from sibling bulk operations like bulkUpdateCasePriority or bulkUpdateCaseStatus, which update status without reprocessing.

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 prerequisite ('The chosen agent must already be connected to the queue as a case-queue-consumer'), which helps the agent determine if the tool is applicable. However, it does not offer explicit guidance on when to use this tool vs. alternatives (e.g., bulkUpdateCaseStatus, stopRun, startRun) or when not to use it. The context is clear but lacks comparative direction.

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 explains the effect of priority on ordering ('due postponed cases are handled first, then higher priority'), guarantees that runs are not interrupted and status is unchanged, and clarifies that setting `none` resets to default. This is valuable since the annotations only provide basic readOnlyHint, idempotentHint, and destructiveHint flags. No contradictions 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 exceptionally concise: three sentences, each earning its place. The first states the core purpose, the second explains behavioral implications, and the third clarifies a special parameter value. It is front-loaded with the most critical information and contains zero fluff or repetition.

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

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

The description provides the core operation and key behavioral traits but leaves out some important context for a 6-parameter tool with nested objects. It doesn't explain the selection mechanism (case_ids vs all_matching with filters/search), the role of queue_id (why it's required), batch size limits, or error handling. While the schema covers these details, the tool description could benefit from a brief overview linking the parameters together.

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 input schema already adequately describes each parameter, including the priority enum and case_ids limits. The description adds minimal parameter-specific insight beyond reinforcing that `none` clears priority (already in the schema). The description does provide broader behavioral context (like how priority affects ordering), but that's not parameter-specific. 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 starts with 'Set the priority of multiple cases,' providing a specific verb and resource. It clearly explains that priority affects only the order of pending cases and explicitly states what the tool does not do (interrupt runs, change status), which distinguishes it from sibling tools like bulkUpdateCaseStatus or bulkReprocessCases. The mention of 'Set `none` to clear priority back to the default' adds further 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 when to use this tool (when you need to change priority for multiple cases) and explicitly says what it doesn't affect (runs, status), which helps avoid misuse. However, it does not provide explicit guidance on when not to use it (e.g., for single cases, use updateCase instead) or name alternative tools. The advice is implied rather than explicit.

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

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

Beyond the annotations, the description reveals meaningful side effects: interrupts active runs, releases case ownership, preserves human-in-the-loop state, and re-dispatches on reset to pending. This substantially exceeds what readOnlyHint/idempotentHint/destructiveHint convey.

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

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

Three dense, purposeful sentences. The first sentence front-loads the primary action, and the next two add essential side-effect details without redundancy or filler.

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

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

The description plus schema covers purpose, side effects, status semantics, and selection options well. It does not mention return/result behavior, and there is no output schema, so a small completeness gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context around status behavior, but the parameters themselves (queue_id, case_ids, filters, all_matching, search) are already well explained 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 clearly states the action: 'Update the status of multiple cases' and enumerates the four settable statuses. It also identifies a distinctive side effect (interrupting active runs and releasing case ownership), which distinguishes it from sibling tools like bulkUpdateCasePriority and bulkReprocessCases.

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 behavioral context for when to use the tool, including what happens to active runs and how pending re-dispatches cases. It does not explicitly name alternatives or state when-not-to-use conditions, 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?

Annotation contradiction: readOnlyHint is false, implying the tool may modify state, yet the description states 'Performs no writes.' This sends conflicting signals to an agent. It also does not describe error behavior for unsupported URLs, which is relevant for a probe tool.

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

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

Three tightly scoped sentences deliver purpose, return value, usage context, and safety in under 40 words. No fluff or repetition.

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

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

For a one-parameter probe with no output schema, the description is fairly rich (return value, usage, safety). However, the contradictory annotation undermines completeness, and it does not state what happens when OAuth is unsupported (e.g., error vs. empty response).

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

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

Schema coverage is 100% and the single parameter mcp_server_url is already described as 'URL of the MCP server to probe for OAuth support.' The description restates this without adding format, constraints, or validation semantics, so it provides no additional value 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 ('Probe') and a resource ('MCP server URL') with a clear goal: discover OAuth Dynamic Client Registration support. It distinguishes itself from sibling tools like probeMcpServer by focusing on OAuth-specific discovery.

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 frames the tool as a precursor to specific connection endpoints, giving a clear when-to-use context. However, it doesn't mention alternatives (e.g., probeMcpServer) or when not to use it, so it misses exclusion 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 readOnlyHint=false (write operation) and no idempotent/destructive hints. The description adds value beyond annotations by stating 'The uploaded bytes are validated before the import becomes a usable Clarity capture', disclosing validation behavior and the state change from pending to usable. No contradiction with annotations.

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

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

Two sentences: the first states the purpose and prerequisite; the second adds a key behavioral detail (validation). Every sentence provides essential information with zero waste.

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

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

Given the tool has 4 required parameters, no output schema, and moderate complexity, the description covers purpose, prerequisite, validation behavior, and the outcome ('usable Clarity capture'). It could optionally mention return values or error handling, but the provided context is sufficient for 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% with each parameter having a description (file_name with pattern, capture_id/process_id as uuids, content_type as enum). The tool description adds no additional parameter meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states it 'completes a Miro artifact import after uploading to the signed URL', combining a specific verb ('complete') and resource ('Miro artifact import'). It distinguishes from sibling tools like completeClarityDocumentUpload, completeClarityVideoUpload, etc., which handle different file types.

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 specifies the prerequisite: 'after uploading to the signed URL', which guides the agent to call this only after the upload step (likely via createClarityArtifactImportUploadUrl). It does not explicitly state when not to use or name alternatives, but the sequential context is clear and sufficient for correct invocation.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the tool is a 'completion' action that does not destroy data. However, the description explicitly mentions 'complete a document capture,' which implies a state transition (e.g., finalizing a capture, possibly making it immutable or triggering post-processing). This adds behavioral context beyond the annotations, such as indicating that the tool likely commits the capture rather than just reading. A slightly higher score is warranted because it clarifies the action's nature, though it doesn't detail side effects like notifications or validation.

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 prerequisite. It is concise and gets the point across without unnecessary words. However, it could be slightly improved by adding a brief note about the required parameters or the state transition, but that might compromise conciseness. A 4 is appropriate for good efficiency with minor room for extra clarity.

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 complexity (3 required params, no output schema, no nested objects), the description is reasonably complete. It tells the agent when to use it (after upload), what it does (completes the capture), and the preceding step (GCS upload). However, it doesn't explain what 'complete' entails (e.g., does it validate the file? trigger processing? return anything?). The high schema coverage reduces the burden, but a brief note on the outcome or behavior would make it more complete. For a simple tool, a 4 is suitable.

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 100% description coverage, with each parameter well-documented (e.g., 'id' is 'The clarity process ID', 'captureId' is 'The capture ID', 'fileName' is 'Name of the uploaded document file'). The description does not add meaning beyond what the schema provides—it doesn't explain how these relate to the GCS upload or what constraints apply (e.g., must match the signed URL? must be the final file name?). Since schema coverage is high, the baseline is 3, which fits 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 uses a specific verb ('Complete') and resource ('document capture') and adds context about the prerequisite step ('after uploading to GCS via signed URL'). This clearly distinguishes it from sibling tools like 'completeClarityArtifactImport' or 'completeClarityTeamDocumentUpload' by specifying the exact domain and phase of the workflow.

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 the prerequisite ('after uploading to GCS via signed URL'), which tells the agent when to invoke this tool—only after a signed URL upload is done. It also places the tool in a clear sequence relative to 'createClarityDocumentUploadUrl' (implied by GCS upload), providing implicit when-not guidance. No alternative tools are named, but the context signals and sibling list show many other 'complete...' tools, so the description effectively narrows the scope.

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 this is a non-read-only, non-idempotent mutation, but the description does not disclose what side effects occur when the capture is completed, whether the operation is reversible, or what happens if the file hasn't actually been uploaded. With no output schema, the description carries a heavier burden but fails to explain the state change 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?

A single sentence with no filler. The key action and object ('image capture') are front-loaded. Given how little is known, it's concise to a fault, but it earns full marks for structure and economy.

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?

This is a mutation tool with no output schema, three required parameters, and no workflow context. It doesn't explain the expected sequence (e.g., upload via signed URL first), what 'complete' changes, or how errors surface. Compared to more self-contained sibling definitions, this one leaves too much unstated for an agent to call it reliably.

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 covers all three parameters with 100% description coverage, and the description's reference to 'image capture' plus parameters like captureId and fileName make the roles fairly clear. The main gap is that id ('clarity process ID') and captureId are not distinguished semantically in the description, but the schema descriptions are sufficient for basic invocation.

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 an image capture') after an upload step, but it's vague about what 'complete' actually does—it doesn't say whether it finalizes a record, marks a status, triggers processing, etc. The tool name and title add little beyond the description, and while it's distinct from sibling upload/complete tools, the core behavior remains unclear.

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

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

There is no guidance on when to use this tool versus its many siblings like completeClarityVideoUpload or createClarityImageUploadUrl. The description or context signals do not explain that this should follow a signed URL upload or that it requires prior creation of the upload URL. An agent must infer the entire workflow.

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, idempotentHint=false, destructiveHint=false. The description adds behavioral context (text extraction, transcript storage) beyond annotations, but does not disclose potential side effects (e.g., triggering Process Landscape generation), idempotency behavior, or authorization requirements. With annotations present, the additive value is modest but positive.

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 that is front-loaded with the action and includes the key outcome. No unnecessary words, but it could be split into two sentences for improved readability. Still, it is efficient and 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 explains what the tool does and its downstream purpose, but omits prerequisites (e.g., the need to first create an upload URL via createClarityOrganizationDocumentUploadUrl) and does not hint at the return value (no output schema provided). For a multi-step process, this leaves gaps in completeness.

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

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

Schema coverage is 67% (2 of 3 parameters have descriptions). The description does not add any parameter-level details beyond what the schema provides; for instance, it does not explain how to obtain interviewId or orgId. Baseline of 3 is appropriate since coverage is between 50% and 80%, and the description does not 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 uses a specific verb ('Complete') and resource ('organization document capture after uploading to GCS') and clearly states the purpose: extracts text and stores it as a transcript for Process Landscape generation. It effectively distinguishes from siblings like completeClarityDocumentUpload and completeClarityTeamDocumentUpload by specifying 'organization'.

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

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

The description implies usage after GCS upload but does not explicitly state when to use this tool versus alternatives like createClarityOrganizationDocumentUploadUrl or completeClarityDocumentUpload. No preconditions, exclusions, or when-not-to-use guidance are provided. The context is implied from the 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, destructiveHint=false, and idempotentHint=false. The description adds meaningful context by explaining the specific effects: extracting text, storing a transcript, and feeding landscape generation. It does not contradict the annotations and provides useful behavioral details beyond the basic 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 sentence that conveys the core purpose and effect without unnecessary words. It is front-loaded and clear, though it could be slightly more concise by removing minor redundancy (e.g., 'after uploading to GCS' is a prerequisite, not the action). Overall, it is efficient.

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 purpose, prerequisite (upload), and downstream integration (feeds Process Landscape generation). There is no output schema, so the description could briefly mention what the tool returns (e.g., success confirmation or error details). However, for a completion action, the current context is mostly adequate.

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 includes detailed descriptions for all three parameters (team_id, fileName, interviewId). The tool description does not add additional meaning or context for individual parameters beyond what the schema provides, so it earns the baseline score.

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 ('complete'), the resource ('team document capture'), and the specific outcome ('extracts text and stores it as a transcript so it feeds Process Landscape generation'). It effectively distinguishes from sibling tools like completeClarityDocumentUpload, completeClarityOrganizationDocumentUpload, and completeClarityVideoUpload by specifying 'team' and the downstream use.

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 indicates a prerequisite ('after uploading to GCS'), but it does not explicitly state when to use this tool versus similar siblings (e.g., completeClarityDocumentUpload, completeClarityOrganizationDocumentUpload) or when not to use it. There is no mention of alternatives or exclusions, leaving room for ambiguity.

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, idempotentHint=false, destructiveHint=false, but the description adds minimal behavioral context. It does not disclose what 'completing' entails (e.g., whether it triggers processing, changes capture state, or has side effects beyond marking completion). No mention of required permissions, rate limits, or irreversibility is provided. The description relies on the user's prior knowledge of the system.

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 conveys the core purpose without extraneous words. It is front-loaded with the verb and resource. However, it could be expanded slightly to include a brief note about the prerequisite step or the tool's role in the upload workflow without losing conciseness.

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 is part of a multi-step upload process (sibling tools include createClarityVideoUploadUrl), the description lacks important context about the entire workflow. It does not explain what happens after completion, what the capture state changes to, or how errors are handled. No output schema is provided, so the description should at least hint at the return value. The description is insufficient for a complete understanding of the tool's behavior.

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

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

Schema coverage is 100% with all three parameters described (id, captureId, fileName). The description does not add any extra meaning beyond the schema; it only mentions the context of GCS upload. The baseline score of 3 is appropriate since the schema already provides sufficient 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 the tool completes a video capture after uploading to GCS via signed URL. It clearly identifies the verb ('complete'), resource ('video capture'), and context ('after uploading to GCS via signed URL'), which distinguishes it from sibling tools like completeClarityDocumentUpload or completeClarityArtifactImport. However, it could be more explicit about the prerequisite step (createClarityVideoUploadUrl) to fully differentiate from other complete 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 description implies the tool should be used after uploading to GCS via a signed URL, which indirectly points to the prerequisite step. However, it does not explicitly state when to use this tool versus alternatives (e.g., other complete tools) or when not to use it. No guidance is given on error conditions, required permissions, or the exact workflow context.

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

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

Annotations only mark the operation as non-read-only, non-idempotent, and non-destructive. The description adds meaningful behavioral context: it stages the change into the draft revision and automatically clears other suggestions that become moot. This goes beyond the annotation flags and informs the agent 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?

The description is a single, tightly-worded sentence that front-loads the action ('Apply a suggestion') and includes necessary behavioral details without any filler. Every word contributes to understanding.

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 conveys the overall workflow (stage change, clear moot suggestions) but leaves gaps about optional parameter semantics and edge cases (e.g., what happens if no draft exists, what 'moot' means exactly). For a mutation tool with four parameters and no output schema, this is adequate 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?

The description does not mention any parameters or tie them to behavior. Schema description coverage is only 50% (id and selected_automation_revision_id have descriptions, while revision_id and create_new_draft lack any). The description fails to compensate for the undocumented parameters, leaving the agent without enough information to set them correctly.

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 the specific verb 'Apply' and identifies the resource 'suggestion', then details the core action: staging the change into the Agent's draft revision and auto-clearing moot pending suggestions. This clearly distinguishes it from sibling tools like rejectAgentSuggestion or getAgentSuggestion.

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 accepting/consuming a suggestion, but it does not explicitly state when to use it versus alternatives or provide any exclusions. Sibling tool names hint at alternatives (e.g., rejectAgentSuggestion) but the description itself offers no 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 convey that this is a write operation (readOnlyHint=false) that is non-idempotent and non-destructive. The description adds the behavioral nuance that a build can be created in the same request. No contradictions with annotations, but side effects beyond creation are not discussed.

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

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

Two sentences with zero wasted words. The core purpose is front-loaded, and the optional build behavior is cleanly appended. Despite the schema's enormous depth, the description stays appropriately sized.

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 carries the full burden for parameters, including nuanced notes on team_id pinning, config versioning, and code-step revision requirements. However, with no output schema, the description does not indicate what the response contains, and no invocation flow or high-level structural guidance is provided.

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 fully documents all 7 parameters and their nested structure. The description only restates the optional build behavior already captured in the schema, adding no new semantic meaning.

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.' This clearly distinguishes it from siblings like updateAgent, deleteAgent, and listAgents. It does not explicitly name a sibling to differentiate from, but the meaning is unambiguous.

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

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

The description gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The second sentence about build configuration is parameter-related, not usage guidance.

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

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

Annotations only indicate non-read-only, non-idempotent, non-destructive. The description adds meaningful behavioral detail: the at-most-one invariant and the 409 conflict response. This goes beyond the annotations and helps the agent anticipate errors.

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

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

The description is two sentences, front-loaded with the key action, and every word adds value. There is no redundancy or irrelevant 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 simple create tool with a rich schema and annotations, the description covers the key unique behavior (409 conflict). It does not mention return values, but the absence of an output schema lessens the need. The main operational context is sufficiently conveyed.

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

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

The input schema provides 100% parameter description coverage, including details for concurrency, agent_id, case_queue_id, and enabled. The description does not repeat or enhance these parameter semantics, 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 uses a specific verb+resource construction ('Create a case trigger for an agent') and clearly distinguishes this from sibling tools like createAgentSlackTrigger or updateAgentCaseTrigger. It also adds a unique constraint (at most one per agent), 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?

The description implies when to use the tool (when creating a case trigger) and hints at a precondition (agent must not already have a trigger) but does not explicitly contrast with alternatives like updateAgentCaseTrigger or previewAgentCaseTriggerConflicts. No explicit when-not 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?

The description merely restates the create action. Annotations already convey that this is a non-read-only, non-idempotent mutation, and the description adds no extra behavioral details (e.g., duplicate name handling, auth requirements, or 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?

The description is a single, front-loaded sentence with only the essential action and resource. It contains no superfluous content; the word 'new' is slightly redundant but does not detract from clarity.

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 lacks any information about return values or success behavior. Since there is no output schema, the agent cannot determine what the tool returns. No usage context or prerequisites are mentioned, making the description insufficient for confident invocation despite the good schema documentation.

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

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

The input schema provides 100% parameter description coverage, including detailed semantics for team_id and parent_folder_id. The tool description adds no parameter information, but because the schema is thorough, a 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 'Create a new agent folder' uses a specific verb and target resource, clearly distinguishing this tool from sibling 'create' tools like createAgent and createCases by naming 'agent folder'. It is concise and 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?

No guidance is provided about when to use this tool versus alternatives like updateAgentFolder or moveAgentsToFolder. There are no stated contexts, prerequisites, or 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds important behavioral details: the one-trigger-per-channel constraint, the requirement for workspace installation/binding, and the specific 400 error on missing prerequisites. No contradiction with annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by a usage constraint and a prerequisite/failure mode. Every sentence carries meaningful information with no redundancy.

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

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

Given the tool's complexity (8 params, no output schema), the description covers purpose, key constraints, prerequisites, and failure conditions. It doesn't explain success return values, but that's not required given rich schema annotations. Overall it provides enough context 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 has 100% parameter description coverage, with detailed explanations for all 8 params including examples, defaults, and the match_rule oneOf structure. The description itself adds no parameter-level detail, but with full schema coverage, 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 clearly states the tool's function: 'Create a Slack channel trigger on an agent... the agent starts a Run whenever a matching message is posted in the channel.' It specifies the verb (create), resource (Slack channel trigger on an agent), and outcome (starts a Run). This distinguishes it from sibling tools like createAgentCaseTrigger, which handles case triggers instead.

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

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

The description provides clear usage context: 'An agent can carry one trigger per channel, so call this once per channel.' It also states prerequisites and a failure condition: 'The Slack workspace must be installed for the team AND bound to the agent's live build first... otherwise this returns 400.' While it doesn't explicitly name alternative tools for other trigger types, the domain is unambiguous.

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 and destructiveHint=false, and the description is consistent with a mutating, prerequisite-issuing operation — no contradiction. The description adds real behavioral context beyond annotations: the two-phase protocol (URL issuance → PUT → finalize), and the fact that the attachment is not visible until finalize. Omits URL-expiry and auth details, but the protocol disclosure is substantive.

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 and roughly 40 words, front-loaded with the primary action and followed by the minimal required continuation. Every clause carries protocol information; there is zero 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 5-parameter tool with no output schema, the description covers the essential flow and hints at the response shape (returned URL and Content-Type). The 'finalize endpoint' is named generically, but the exact sibling tool finalizeCaseAttachment exists in the tool list, so an agent can chain the calls. Minor gaps — URL expiry, auth requirements, and exact response fields — keep it 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 only 40% — case_id and queue_id are documented, but filename, mime_type, and size_bytes have no schema descriptions. The tool description does not compensate: its only indirect hint is that the returned Content-Type relates to mime_type, and it says nothing about filename or size_bytes semantics beyond what the schema's constraints already imply.

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 — issuing a signed URL for uploading a file to a case — with a clear resource and scope. The 'to a case' qualifier and the finalize-endpoint reference distinguish it from the many sibling upload-URL creators (createFileUploadUrl, createPulseDashboardAttachmentUploadUrl, createClarityImageUploadUrl, etc.) without needing to open any schema.

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

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

Describes the full protocol: PUT the bytes to the returned URL with the returned Content-Type, then call the finalize endpoint for the attachment to become visible. This clearly tells the agent that this tool alone is insufficient and routes it to the mandatory follow-up step. However, it does not explicitly name alternatives or state when not to use this tool versus other upload-URL siblings.

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

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

Beyond the annotations, the description discloses important behavioral details: the addition targets the current version/build-set, and the call fails with 409 under two concrete conditions. This gives an agent meaningful operational understanding without contradicting the readOnlyHint/idempotentHint/destructiveHint 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 most important action is front-loaded in the first sentence, and each subsequent sentence adds valuable context. Minor redundancy exists between 'current rubric set' and 'current version (build-set),' and the final clause is slightly awkward, so it is not a model of maximum conciseness.

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

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

For a three-parameter mutation with no output schema, the description is complete: it explains what the tool does, what a case-level rubric means, where it is added, when it cannot be added, and the numerical cap. No critical information an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents queue_id, title, and description with clear descriptions. The tool description reinforces the Pass/Fail semantics but does not add meaningful parameter-level detail 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: 'Add one case-level evaluation rubric to a queue's current rubric set.' It clearly distinguishes this tool from siblings like createEvalRubric by scoping it to queue-level, case-level rubrics, and from update/delete/replace siblings by the 'Add one' framing.

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: adding to the queue's current build-set that new cases are judged against. It also states preconditions and failure conditions (409 before the first Agent-processed case settles and once the version holds 12 rubrics), though it does not explicitly name alternatives such as replaceCaseQueueEvalRubrics or createEvalRubric.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds valuable behavioral context: providing both case and cases returns 400, missing labels are auto-created on the queue, and priority semantics are explained. This goes beyond the annotation flags without contradicting them.

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

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

The description is front-loaded with the primary purpose in the first sentence and then provides essential details in a dense but organized paragraph. The priority explanation is slightly verbose but contains important behavioral context, so no sentence is wasted.

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

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

Given the tool's complexity (nested objects, batch limits, mutual exclusivity, side effects on labels), the description covers the key invocation requirements well. It doesn't mention the response shape or error handling beyond the 400, and there is no output schema, but the core usage is sufficiently complete for an agent to invoke 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 only 33% (queue_id has a description; top-level `case` and `cases` properties lack direct descriptions). The description compensates by explaining that `case` is a single object and `cases` is an array of 1-100, and details the nested fields (title max 500 chars, data, labels, priority). It adds meaning beyond the bare 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 'Create one or more cases in a queue', which is a specific verb + resource + scope statement. It clearly distinguishes itself from sibling tools like createQueue, createQueueLabel, and updateCase by focusing on case creation with batch support.

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 on how to use the tool: provide either a single `case` object or a `cases` array (1-100), and notes that providing both returns 400. It doesn't explicitly name alternatives (e.g., use updateCase for existing cases), but the mutually exclusive input pattern and queue context make usage unambiguous.

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 provide basic boolean hints (non-read-only, non-idempotent, non-destructive). The description adds significant behavioral context: the tool only creates a URL, does not perform the upload, and the import must be completed via a separate step. This clarifies the multi-step nature without contradicting the annotations.

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

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

The description is three sentences with no superfluous words. The first sentence states the core action, the second lists formats, and the third provides essential workflow instruction. Every sentence adds value, making it a model of conciseness.

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 workflow but lacks details about the return value structure (e.g., that the signed URL is a response field) and constraints like file size limits or URL expiration. Since there is no output schema, this omission is a gap. With strong schema coverage, it is adequate 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?

With 100% schema description coverage, the baseline is 3. The tool description repeats the supported formats already encoded in the file_name pattern and content_type enum but adds no additional meaning beyond schema details, such as parameter interdependencies or 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 clearly states the tool creates a signed upload URL for importing a Miro export into a Clarity v2 process, listing supported file formats. This distinguishes it from sibling URL creators like createClarityDocumentUploadUrl and createClarityVideoUploadUrl, which serve different content types.

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 (importing Miro exports) and outlines the mandatory follow-up steps (upload file, complete import). While it doesn't explicitly state when not to use it or list alternatives, the context is strong enough for an agent to make a correct 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 adds useful behavioral context beyond the annotations: the URL is signed and uploads go directly to GCS. However, it does not disclose URL expiration, the required upload method, or any side effects such as creating a pending upload record, which matters given readOnlyHint=false and 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?

The description is a single sentence with no filler, action first, and a compact list of supported formats. Every component 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 has no output schema, and the description does not explain how the returned signed URL should be used (HTTP method, headers, direct PUT to GCS) or that a sibling tool like completeClarityDocumentUpload may need to be called afterward. That missing workflow context is a significant gap for an agent executing the upload end to end.

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 description is not required to repeat parameter details; the format list usefully maps to the contentType enum. It adds no meaning beyond the schema for id or fileName, and 'BPMN' is slightly ambiguous against the enum, which lacks a specific BPMN MIME type.

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 signed URL') and a specific resource (Clarity document upload), and it enumerates the supported file types. It is clear about what the tool does, though it does not explicitly differentiate itself from sibling upload-URL tools like createClarityTeamDocumentUploadUrl or 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 provides clear context: use this tool when you need to generate a signed URL to upload supported document types directly to GCS. It does not state explicit alternatives or when-not-to-use conditions, but the format list and 'directly to GCS' give a solid usage signal.

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, not idempotent, and not destructive. The description adds no behavioral context beyond the name. It does not disclose what happens if a folder with the same name exists, whether it overwrites or fails, or any side effects. With annotations present, the description should at least confirm or clarify the mutation 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 a single short phrase, but it is under-specified. It adds little value beyond the title and name. While concise, it does not earn its place by providing useful information. A slightly longer description with more details would be better.

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

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

The description is incomplete for a creation tool. It does not explain what the folder is for, how to use the optional team_id, or what the return value is. Given the absence of an output schema, the description should cover what happens on success or failure. The schema and annotations are minimal, so the description carries more burden.

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 provides adequate descriptions for both parameters. The tool description adds no additional meaning or context about parameters. Baseline is 3, and the description does not exceed that.

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 'Create a process folder' clearly states the action (create) and the resource (process folder). It distinguishes from sibling tools like createClarityProcess or createClarityProcessLabel, which create different entities. However, it does not elaborate on what 'process folder' means, which could be ambiguous without context.

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. It does not mention prerequisites, exclusions, or the optional team_id parameter. Without this, an agent may not know when creating a folder is appropriate or how to choose between this and other create tools.

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

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

Annotations already indicate readOnlyHint=false, so the agent knows it's a write operation. The description adds no additional behavioral context beyond this, such as idempotency effects, conflict behavior, or what happens to existing guidance. It does not contradict annotations, but fails to add value beyond them.

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

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

The description is a single, well-structured sentence of 11 words. It is front-loaded with the verb and resource, contains no filler or redundant information, and is appropriately concise for a tool with two parameters.

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

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

Given the tool's simplicity (two parameters, no output schema, 100% schema coverage), the description covers the basic purpose but does not explain what a 'transformation guidance message' is, what the return value is, or that the 'id' must reference an existing clarity process. Additional context would improve usability.

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 input schema already documents both parameters ('id' and 'content') with descriptions. The description does not add any additional meaning beyond what the schema provides, meeting the baseline expectation but not exceeding 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 states 'Create a new transformation guidance message for a clarity process' with a specific verb (create) and resource (transformation guidance message). It clearly distinguishes from the sibling tool 'updateClarityGuidance' by implying creation of a new object rather than modification.

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, no prerequisites, no context about when not to use it, and no mention of related tools like 'updateClarityGuidance' or coordination with 'createClarityProcess'.

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 indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds that this creates a signed URL rather than performing the upload itself, which is useful. However, it does not disclose expiration behavior, upload method, or any follow-up requirements after the upload is made.

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 action, target resource, supported formats, and destination. There is no filler or redundant repetition of the title beyond what is necessary for clarity.

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 relatively simple signed-URL generation tool with well-documented parameters, the description conveys the essential behavior and return concept. Minor gaps remain, such as URL expiration and the need to call a completion tool afterward, but the tool is still understandable and invocable from the information provided.

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 every parameter already has a meaningful description in the schema. The tool description does not add parameter-level 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 specifies a concrete verb ('Create'), a clear resource ('a signed URL for uploading a ... image'), and the target destination ('directly to GCS'). It also names the supported formats (PNG, JPEG, WebP), which distinguishes it from sibling tools like createClarityDocumentUploadUrl or createClarityVideoUploadUrl.

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 generating image upload URLs, but it does not explicitly state when to choose this over alternatives, nor does it mention the related completion step such as completeClarityImageUpload. Usage guidance is indirect and left to inference from sibling tool names.

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

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

The description discloses a critical behavioral trait beyond the annotations: 'creating a new link invalidates any prior active link for the process.' This is a destructive side effect that the annotations (destructiveHint: false) do not capture. The description correctly warns the agent about this irreversible invalidation, which is excellent 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 long with zero wasted words. The first sentence states the purpose, and the second provides critical behavioral and access context. Every sentence adds value and is front-loaded.

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

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

Given the tool's simplicity (1 parameter, no output schema, clear annotations), the description fully covers the necessary context: what it does, who can use it, and the side effect of link invalidation. There are no gaps in actionable information.

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 a single parameter (process_id) that is well-documented in the schema with format and pattern. The description adds the context that the link is 'process-scoped', which reinforces the parameter's role. Since the schema already handles parameter meaning well, 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 states the verb ('Create or regenerate'), the resource ('process-scoped Clarity interview invite link'), and the scope ('process-scoped'). It also differentiates from siblings like deleteClarityProcessInviteLink and getClarityProcessInviteLink by specifying creation behavior.

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 specifies who can use the tool ('Only the process creator or team managers can create invite links'), which provides important access context. It also mentions that creating a new link invalidates prior active links, hinting at when not to use it (if you want to keep existing links). However, it does not explicitly name alternatives like getClarityProcessInviteLink or deleteClarityProcessInviteLink.

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 permission requirements (admin+ for active, any member for proposal) and the idempotent behavior of proposal mode, which goes beyond the sparse annotations (all false). It clarifies that active creation is not idempotent, providing valuable behavioral context for an agent.

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

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

The description is two concise sentences, front-loaded with the primary purpose and then permission context. No redundant or filler information is present, making it highly efficient.

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 and permission nuances, but omits details about parameters like parentId and ownerLabel, and doesn't mention return values (no output schema). For a 6-parameter creation tool, this is incomplete, though it does address key semantic distinctions.

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 only 33% schema coverage, the description should compensate for parameter explanations, but it only sheds light on creationMode (via permissions and idempotency). It does not clarify orgId, name, parentId, ownerLabel, or description, leaving significant gaps for an 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 'Create an area folder in the process tree' with a specific verb and resource, clearly distinguishing it from sibling tools like createClarityFolder or createClarityProcess. It also explains the active/proposal modes, which further clarifies the tool's 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 usage context by explaining permission requirements for active vs proposal modes, guiding when each should be used. It does not explicitly compare to alternative tools, but the clear verb and resource make the primary use obvious, and the mode-specific guidance is a strong point.

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 it creates a signed URL (not the actual upload), which is a key behavioral trait. However, it fails to disclose URL expiration, authentication requirements, or the need for a subsequent completion step. Annotations are neutral and not contradictory, but the description does not sufficiently inform the agent about side effects or prerequisites.

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

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

A single, clear sentence with no extraneous words. All essential elements (verb, resource, file types, scope) are included without repetition.

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

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

The description omits the workflow context: after obtaining the signed URL, the agent must upload the file and then call completeClarityOrganizationDocumentUpload. No output schema is provided, and the description does not indicate what the response contains (e.g., URL, fields). For a tool that creates a pre-upload resource, this is a significant gap.

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

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

Schema coverage is 67% (orgId lacks description). The description adds value by mapping file types (PDF, TXT, Markdown, BPMN) to MIME types in the contentType enum, though BPMN maps to application/xml which may be unclear. The fileName and orgId parameters receive no additional semantic explanation beyond what the schema provides. Overall, moderate added value.

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

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

The description clearly states the tool creates a signed URL for uploading documents (PDF, TXT, Markdown, BPMN) at the organization level, distinguishing it from sibling tools like createClarityDocumentUploadUrl (likely user-level) and createClarityTeamDocumentUploadUrl (team-level) through the explicit 'organization-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?

No explicit guidance on when to use this tool vs alternatives (e.g., createClarityDocumentUploadUrl for personal uploads, or the completion step completeClarityOrganizationDocumentUpload). The description implies organization-level context but does not provide rules for selection or prerequisites.

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 provide generic false hints. The description adds useful behavioral details: name defaults server-side when omitted, and response uses camelCase createdAt for FE compatibility. The 'Builder+' hint also suggests a permission requirement. It does not fully describe all side effects, but covers key behaviors beyond 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, front-loaded with purpose, and each clause adds value: scope, parameter default, and return format. There is no redundancy or fluff.

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

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

For a create tool with two optional parameters and no output schema, the description covers purpose, scope, name default, and a return format note. It doesn't list the full response structure, but the tool is straightforward and the schema covers parameter edge cases thoroughly.

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 detailed descriptions for both name and team_id. The description's mention of name default simply reiterates the schema. It adds no additional parameter meaning beyond what the schema already 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 action and resource: 'Create a new Clarity v2 process'. This clearly distinguishes it from sibling tools like createClarityProcessLabel, createClarityProcessLink, and createClarityProcessNode, as well as from update/duplicate process 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 description specifies usage context: 'for the current team (Builder+)' and notes the optional name default. It does not explicitly mention alternatives or exclusions, but the target scope and permission hint are clear enough for a create operation.

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 idempotent (idempotentHint=false). The description adds no additional behavioral context, such as uniqueness of the 'value' field, effects on existing processes, or whether colorHue affects display.

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

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

The description is a single concise sentence that front-loads the action. However, it is so brief that it borders on under-specification, though it is not redundant or bloated.

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

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

Given the absence of an output schema and minimal annotations, the description should provide more context about what a process label is, how it relates to processes, and any constraints (e.g., uniqueness, naming rules). It currently only gives the most basic purpose.

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 three parameters with types and constraints, but the description mentions only 'for an organization' loosely mapping to orgId. It does not explain the semantics of 'value' (likely the tag text) or 'colorHue' (display color), leaving the agent without meaningful guidance for a tool with 0% schema coverage in 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 tool creates process tags for an organization, using the verb 'create' and resource 'process tags'. However, it does not differentiate from related sibling tools like assignClarityProcessLabels or updateClarityProcessLabel, as all involve process labels.

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 alternatives such as assignClarityProcessLabels or createClarityProcess. There is no mention of prerequisites, creation context, or what distinguishes a label from a process.

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 valuable behavioral context beyond the annotations: it discloses a permission requirement ('when the caller can manage both endpoint teams') and an idempotent-like behavior (if an identical link exists, the existing link is returned). The annotations only supply readOnlyHint, idempotentHint, and destructiveHint flags, which do not capture this nuance. The description 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 two sentences, with the core action stated first and the duplicate-handling behavior as a concise second sentence. No wasted words or redundant repetition of schema information.

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

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

Given the tool has no output schema and moderate complexity (6 parameters, creation behavior), the description covers the purpose, a key permission constraint, and a significant edge case (duplicate links). It doesn't explain error cases (e.g., what happens if the caller lacks permission) or return object shape, but for a create-type tool with minimal annotations, it is reasonably 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?

The schema description coverage is 83%, so most parameters already have meaningful descriptions. The tool description reinforces that source_node_id, target_node_id, and type together define a unique link ('the same live source, target, and type'), but it doesn't add substantial new semantics beyond what the schema's per-parameter descriptions already offer. 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 starts with 'Create a process-to-process link', which is a specific verb and resource. It further clarifies the scope ('in the organization's Clarity landscape') and distinguishes from sibling tools like createClarityProcess (which creates a node) and updateClarityProcessLink (which updates rather than creates). The behavior of returning an existing link further clarifies the tool's unique role.

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

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

It provides a clear precondition ('when the caller can manage both endpoint teams'), which is useful guidance. However, it doesn't explicitly mention alternatives like updateClarityProcessLink or when not to use this tool. The verb 'create' implies new links, but no direct comparison to sibling tools is given.

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

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

Annotations already mark readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds the target audience (team manager or organization admin+), which is helpful authorization context beyond annotations. However, it doesn't disclose whether the operation is reversible or what happens to the source process (e.g., is it moved or copied?). With annotations present, the description provides some extra value but not deep behavioral details.

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

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

Two sentences, zero waste. The first sentence states the purpose and the second provides usage differentiation. Every word earns its place. Good front-loading.

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 3 required parameters, no output schema, and moderate sibling complexity, the description covers the core action and differentiation well. It lacks any mention of return value (though no output schema exists) or error conditions (e.g., what if the process is already filed). But for a simple filing operation, this is mostly adequate.

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%: parentId and processId have descriptions, orgId does not. The description adds context about processId by explaining that Unsorted processes are listed by getClarityProcessLandscape, which the schema doesn't mention. This helps the agent understand where to find the processId. However, no additional info for orgId or parentId beyond the schema. The description compensates for the coverage gap partially.

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 'File an existing Clarity process into an area of the process landscape', using a specific verb ('File') and resource ('process into landscape area'). It distinguishes from the sibling tool 'proposeClarityLandscapeProcess' by explicitly contrasting the use case (existing vs. brand-new process).

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 explicit guidance on when to use this tool: for processes that already exist but sit in 'Unsorted'. It also names the alternative tool ('proposeClarityLandscapeProcess') and its specific purpose (creating a brand-new one), making the choice unambiguous.

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, destructiveHint=false, so this is a non-read, non-destructive mutation. The description adds that the tool creates a signed URL (not the upload itself), which is a key behavioral trait beyond the annotations. The file format restrictions and team scope are also disclosed. No contradictions 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, well-structured sentence that clearly states the action, resource, file types, and scope. It is concise with no filler, front-loading the core purpose at the beginning.

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 has 3 parameters (100% schema coverage), no output schema, and annotations covering safety, the description adequately explains the tool's purpose and scope. It could be improved by noting that the signed URL is typically used for a subsequent PUT request, but it remains complete for an upload URL creation 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?

The input schema has 100% coverage with descriptions for all three parameters. The description lists supported file types (PDF, TXT, Markdown, BPMN) that map to the contentType enum, which adds useful context. However, it does not add meaning beyond the schema for 'team_id' or 'fileName', so baseline 3 plus 1 for the added file type context.

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 specifies the verb ('create'), the resource ('signed URL for uploading a PDF, TXT, Markdown, or BPMN document'), and the context ('team-level Clarity capture'). It effectively distinguishes this tool from siblings like 'createClarityDocumentUploadUrl' (non-team) and 'createClarityArtifactImportUploadUrl' (artifact import).

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 this tool (when you need to upload a supported document to a team's Clarity capture), and the file types and scope are explicit. Among 100+ siblings, specific alternatives like 'createClarityDocumentUploadUrl' for non-team uploads exist, but the description does not explicitly name when not to use this tool or mention alternatives, leaving some gap.

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

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

Annotations already indicate readOnlyHint=false, so the agent knows this is not a read-only operation. However, the description adds no behavioral context beyond that. It does not disclose whether the URL expires, whether calling this tool creates a persistent record, what permissions are required, or what happens if called multiple times. The description contributes negligible value on top of 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 sentence: 'Create a signed URL for uploading a video file directly to GCS'. It is front-loaded with the key action and resource, contains no filler, and every word contributes to the purpose. This is an ideal level of conciseness.

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 4 parameters, no output schema, and no nested objects. The description does not explain what the tool returns (the signed URL), nor does it mention important details like URL expiration, HTTP method for upload, or the relationship to completeClarityVideoUpload. Given the lack of output schema, the description should fill this gap but does not, leaving the agent without crucial usage context.

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

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

Schema coverage is 100% with all parameters described in the schema. The description adds no information about the parameters beyond what the schema already provides. Baseline 3 is appropriate as the schema does the heavy lifting and the description neither improves nor detracts from parameter understanding.

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

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

The description clearly states the tool creates a signed URL for uploading a video file to GCS. The verb 'create' and resource 'signed URL for uploading a video file' are specific. However, it does not differentiate from sibling tools like createClarityDocumentUploadUrl or createFileUploadUrl, which perform similar actions for other content types. The name provides some differentiation but the description could explicitly note the video-specific context.

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. It does not mention the required prerequisite (a clarity process ID), the typical workflow (upload the video using the signed URL, then call completeClarityVideoUpload), or any restrictions. Sibling tools like completeClarityVideoUpload exist, but the description does not reference them or clarify the tool's place in the pipeline.

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 operation (readOnlyHint=false). The description adds the useful caveat that OAuth flows require an interactive browser flow and different endpoints, but does not disclose other behavioral aspects like permissions, response format, or side effects beyond creation. It neither contradicts nor richly supplements 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 two sentences and front-loaded with the core purpose. Every sentence adds value, and the OAuth exclusion is compactly stated. No fluff.

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

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

Given the complexity (8 parameters, nested headers object, no output schema), the description is adequate for high-level understanding but incomplete for invocation. It explains the core purpose and OAuth exclusion but lacks detail on required parameters, request examples, or return behavior.

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

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

Schema description coverage is only 13% (only team_id has a description), so the description must compensate for the other 7 parameters. It does not explain the meaning or usage of name, provider, auth_method, headers, server_url, type, or custom_integration_id. The phrase 'user-provided connection (custom MCP server)' hints at provider/type but is insufficient.

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

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

The description clearly states the tool's action ('Create a new user-provided connection') and specifies the resource ('custom MCP server') and scope ('for the current team'). It distinguishes this tool from siblings like createCredential and createCustomIntegration by focusing on user-provided MCP connections.

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 explicit when-to-use guidance and an explicit exclusion: OAuth-based integrations should use dedicated OAuth endpoints instead of calling this endpoint directly. This is a strong alternative referral that prevents misuse.

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, non-destructive operation. The description adds useful behavioral constraints beyond that: at least one of password/otp_secret is required, shared defaults to false, and manager role is needed for shared logins. It stops short of describing side effects like duplicates or return payload.

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

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

Two concise sentences, front-loaded with the core action. Every clause adds value—the validation requirement, the default, and the role condition—with no filler.

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

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

For a 7-parameter tool with low schema coverage and no output schema, the description covers the most critical semantic constraints but omits several parameters (username, userId, domain) and does not mention return behavior. The team_id parameter is already explained in the schema, so this is only partially 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 only 14%, so the description must compensate. It adds meaningful semantics for password, otp_secret, and shared, but leaves username, userId, and domain unexplained beyond their field names. Partial compensation is present, but not enough to fully bridge the schema 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 starts with 'Create a login', giving a specific verb and resource that clearly distinguishes it from updateCredential, createSecret, and other create tools. It also adds a key constraint (at least one of password or otp_secret) that further defines the tool's purpose.

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

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

The description provides clear context about when to use the tool: personal by default, and shared only when manager role is available. It does not explicitly name alternatives or exclusion cases, but the context is sufficient for most agent decisions.

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 the tool is a write operation (readOnlyHint=false), and the description adds valuable context: it creates a team-level catalog entry rather than a live connection and requires a manager-or-above role. This goes beyond what annotations provide, though it does not disclose the return format or 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?

The description is two concise sentences, front-loaded with the core purpose ('Create a custom integration type') and immediately clarifying the team-level and MCP connection context. Every word earns its place without 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 provides a solid high-level understanding but lacks essential details for a tool with 6 parameters and no output schema. It does not explain what the tool returns (e.g., the created integration ID), the meaning of auth_method options, or when oauth_client_id/secret are needed. This leaves the agent under-informed for correct invocation.

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

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

Schema description coverage is only 17% (only team_id has a description), and the description does not compensate by explaining the other parameters (name, server_url, auth_method, oauth fields). The agent is left without guidance on how to fill the required parameters or their meaning.

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 creates a 'custom integration type (team-level catalog entry)' that users can later connect as MCP connections. This specific verb+resource combination effectively distinguishes it from sibling tools like createConnection, which presumably creates actual connections rather than catalog types.

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 (to define a reusable integration type) but does not explicitly name alternatives or state when not to use it. The role requirement ('manager-or-above') is a useful prerequisite but not guidance on choosing between this and similar create tools.

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

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

Adds valuable behavioral detail beyond the annotations: the 5-custom-rubric limit, the 409 failure once reached, and the default-to-live-build behavior. The annotations only declare write/non-idempotent/non-destructive, so this extra context meaningfully improves 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?

Three tight sentences: purpose first, then constraint/failure mode, then default behavior. Every sentence contributes information with no redundancy or fluff.

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

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

Covers the core purpose, resource limits, default target, and failure mode. It doesn't mention the selected_automation_revision_id behavior, but the schema description handles that. With no output schema, the absence of return-value details is acceptable.

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

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

Schema coverage is 100% for all 5 parameters, so the schema already documents each field. The description repeats build_id's default-to-live-build behavior but does not add substantially new parameter-level meaning beyond what the schema provides.

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

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

The description uses a specific verb ('Add') and resource ('Agent-specific evaluation rubric') targeting a 'build', clearly distinguishing it from update/delete/replace rubric tools. It also scopes the operation to the agent and identifies the default 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?

Provides clear context: defaults to the live build, allows targeting a specific revision with build_id, and warns about a 5-rubric ceiling with a 409 failure. It doesn't explicitly name alternatives, but the action semantics and sibling names (update/replace/delete) make the intended use 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 readOnlyHint=false and destructiveHint=false. The description adds that it produces a signed URL for direct GCS upload, clarifying it does not upload the file itself. However, it does not disclose URL expiration, upload size limits, or required HTTP method, which are relevant behavioral traits for a signed-URL generator.

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 that states the core function without filler. Every word earns its place.

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

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

The tool is simple and the schema covers parameters, but with no output schema, the description should ideally mention return format, URL expiration, or next steps (e.g., use returned URL in PUT/POST). The current one-liner is minimally viable but leaves these details implicit.

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

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

The input schema has 100% description coverage for all three parameters (fileName, contentType, team_id), so the description does not need to add parameter semantics. The description adds no parameter-specific meaning beyond the schema, hence baseline 3.

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

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

The description uses a specific verb ('Generate') and resource ('signed URL for uploading a file directly to GCS'). It clearly states the tool's function. However, it doesn't distinguish from sibling upload-URL tools like createSandboxUploadUrl or createPulseDashboardAttachmentUploadUrl.

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

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

The description provides no explicit guidance on when to use this tool versus alternative upload-URL tools. It lacks exclusions, prerequisites, or context about which file types or teams it applies to. The only implied context is 'directly to GCS,' but no alternatives are named.

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 the role requirement and scope, which is useful behavioral context for an agent. 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?

Two short sentences with no unnecessary detail; the key 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?

For a simple create tool with two parameters and no output schema, the description covers purpose, prerequisite role, and scope. It doesn't mention what happens on success (e.g., return value), but this is a minor gap.

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

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

The schema describes orgId with a UUID format, but name lacks a description. The description does not elaborate on parameter semantics, relying on the schema and the simple parameter names. With 50% schema coverage, the description adds no extra meaning.

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 'Create' and the resource 'a new team under an organization you administer', distinguishing it from sibling team-related tools like createTeamInvite or listOrgTeams.

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 specifies the prerequisite of administering an organization and the required role, which helps determine when to use this tool. However, it does not explicitly contrast with alternative team creation or invitation tools.

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

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

Annotations already indicate this is not read-only, not idempotent, and not destructive. The description adds valuable behavioral details: generation is asynchronous and requires polling GET /artifacts/{artifactId}, and visibility defaults to private unless 'team' is set, with permission levels affecting sharing. This exceeds what annotations alone provide.

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

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

The description is three sentences, each earning its place: the main action, the asynchronous polling behavior, and the sharing semantics. It is front-loaded with the primary purpose and has no fluff.

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

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

The description covers key aspects: creation, async polling, and sharing semantics. However, it omits the 'connection_ids' parameter entirely and does not explicitly describe the return format beyond implying an artifact ID. Given the absence of an output schema, these gaps make it incomplete for a tool with 4 parameters.

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 0% schema_description_coverage, the description must compensate. It explains 'message' as a natural-language prompt, and details the semantics of 'visibility' and 'permission'. However, 'connection_ids' is not mentioned at all, leaving that parameter undocumented. Partial compensation, but not complete.

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?