RooQuiz

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: the note is visible only to team members and never to the respondent, the 2000-character limit, the optional recordId context, and the non-idempotent timeout behavior. The non-idempotency warning is especially valuable because it directly affects how an agent should handle retries.

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

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

Three sentences with zero waste. The core action and visibility constraint are front-loaded, the character limit and optional parameter are stated compactly, and the non-idempotency warning is placed at the end where it is most actionable. Every sentence earns its place.

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

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

For a 3-parameter tool with 100% schema coverage, an output schema, and annotations covering the safety profile, the description is complete. It covers the action, scope, visibility, limits, optional parameter semantics, and retry behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds meaning by explaining the purpose of the note ('internal follow-up'), the visibility constraint, and the optional recordId as 'context'. It doesn't add syntax details, but the schema already covers those, so a 4 is appropriate.

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

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

The description states a specific verb ('Write'), a specific resource ('internal follow-up note on a lead'), and a clear scope ('of the current team'). It also distinguishes itself from reading notes by pointing to get_lead(includeComments: true), and the sibling list shows no other add-comment tool, so there is no 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?

The description explicitly says when to use this tool (to write an internal follow-up note), what it is not for (visible to team members only, never to the respondent), and how to read existing notes (get_lead with includeComments: true). It also gives a clear retry policy: check first, then retry only if the note is really missing. This is explicit when/when-not guidance.

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

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

Goes well beyond the annotations: discloses non-idempotency and the timeout/duplicate risk with a concrete retry protocol, states that Breaker ignores all fields other than formId and type, and gives per-plan question-count limits (Free 50, Pro unlimited, ai_quiz 20). None of this contradicts readOnlyHint=false / destructiveHint=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?

Front-loaded with the core action and item categories, then behavioral warnings. Dense but every sentence carries information an agent needs; the plan-limit sentence is slightly long but not padding.

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

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

For a 30-parameter mutation tool with an output schema already covering return values, the description supplies what the schema cannot: idempotency behavior, quota constraints, type-specific field requirements, and a pointer to authoritative field docs. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is already 100% (each parameter defers to create_form questions[]), so the baseline is 3; the description adds real value on top by stating the per-type minimum (Breaker needs only formId+type) and that Statement/Swiper are display-only. It still defers almost all field meaning to another tool rather than restating it, hence not a 5.

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

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

States a specific verb (append) plus a precise scope (to the end of a form) and enumerates the three item categories it accepts: question, page break (Breaker), and display block (Statement/Swiper). The 'append to the end' wording also implicitly separates it from insert_question in the sibling set.

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

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

Gives a clear when-not ('Configure random_knowledge_quiz question banks in the web app') and routes the agent to create_form questions[] for field-level rules, plus plan-limit conditions that affect whether the call will succeed. It does not explicitly contrast with insert_question or update_question, which is the main remaining 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 indicate readOnlyHint=false and destructiveHint=true, but the description adds valuable behavioral context: 'Each actual change is recorded on the lead's timeline' and describes the aggregated notification and email behavior, including that reassigning the same owner does not trigger another notification. This goes beyond the annotations and helps the agent understand side effects and user-facing impacts.

Agents need to know what a tool does to the 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 somewhat long but every sentence provides useful guidance: purpose, batching rule, assignee requirements, unassign method, and side effects. It is front-loaded with the core action and then provides necessary operational details. It is not overly verbose given the amount of information needed for correct usage.

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

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

For a mutation tool with an output schema and two parameters, the description covers all essential aspects: what to pass, how to batch, who qualifies as assignee, how to unassign, and what side effects occur (timeline recording, notifications). It also points to a sibling for eligible assignees. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters already have detailed descriptions (e.g., 'The member userId to assign to, or "me"... Omit (or pass null) to clear the assignee.'). The description repeats these details but adds no new parameter-specific information beyond the schema. The batching instruction (up to 50) is also already in the schema's maxItems. Therefore, the description adds minimal extra parameter 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 action: 'Assign one or more leads of the current team to a member, or clear the assignee.' This is a specific verb (assign) with a specific resource (leads) and an additional action (clear). It distinguishes itself from siblings like set_lead_tags or update_lead by focusing on the assignment/ownership change.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage rules: 'Pass every lead id in a single call (up to 50) — do not loop one call per lead.' It also specifies prerequisites (assignee must be an active non-viewer member, see list_lead_settings.assignableMembers) and explains how to unassign (omit/null). It does not explicitly name alternative tools for the same operation, but it points to a sibling for prerequisite info, and the 'do not loop' instruction is a clear when-not-to-do.

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

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

Beyond the annotations, it discloses that the operation is non-idempotent, that a timeout may still have succeeded, and that blind retries can create duplicates. It also states plan limits (Free 50 questions, ai_quiz 20 everywhere) and that only the primary language is created, which are important operational traits not present in the annotations.

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

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

The core action is front-loaded, and the length is justified by the tool's complexity and nested schema. It remains dense and somewhat wall-of-text in the middle, but most sentences carry scene-specific or operational information rather than filler.

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

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

Given the complex nested schema, multiple scenes, output schema, and non-idempotent write behavior, the description covers the critical workflow, scene restrictions, plan limits, translation boundary, and retry caution. An agent has enough context to call it correctly without opening sibling tools first.

Complex tools with many parameters or behaviors need more documentation. 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 carries the detailed parameter semantics. The description still adds cross-parameter workflow meaning by tying scene choice to required report/outcome/dimension fields and by explaining that structuredContent.fields carries question codes that can then be referenced in formulas.

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

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

The description opens with a specific verb and resource: 'Create a form in the team this token is bound to.' It immediately distinguishes the bulk-create path from per-question alternatives by saying to pass the questions array and report configuration in one call rather than following up.

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

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

It gives explicit scene-by-scene guidance: outcome_quiz requires report.outcomes at create time, ai_quiz uses report.aiReport and custom question codes, and scored_quiz dimensions can be defined in the same call. It also names alternatives for adjacent needs: create_form_translation for other languages and update_form / set_dimension_analysis for later report edits.

Agents often have multiple tools that could apply. Explicit usage 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 a non-read-only, non-destructive, open-world operation, but the description adds substantial behavioral detail: it clones template structure, scoring/report configuration, visual settings, and all language versions in one call. Critically, it warns that the call is not idempotent and that retrying after a timeout may create duplicates. This goes far 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 four sentences, each earning its place: core action, what is cloned, post-creation workflow, and idempotency warning. It is front-loaded with the main purpose and the additional caveats are critical rather than filler.

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

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

For a tool that creates from a template and has non-idempotent behavior, the description covers the core semantics, the source of template IDs, the relationship to sibling tools, and the retry risk. An output schema exists, so return-value documentation is not required here, and no critical invocation detail appears missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by directing users to list_templates for finding templateId and noting that title overrides the template title. It does not add information about formatting or constraints beyond the schema, but the extra guidance around template ID discovery and title override justifies a slight upgrade.

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

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

The description clearly states the action: 'Create a new form in the current team from a public template.' It distinguishes itself from sibling create_form by explicitly saying it is the fastest path when a suitable template exists and should be preferred over building from scratch. It also points to list_templates for finding template IDs, removing ambiguity about resource provenance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explicit when-to-use guidance: 'This is the fastest way to build a quiz when a suitable template exists — prefer it over building from scratch with create_form.' It also explains the post-creation workflow with update_form / update_question and provides a concrete prerequisite via list_templates. This is strong routing guidance relative to sibling 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 declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the safety burden is light. The description adds real behavioral context beyond that: the source text is cloned as an initial draft, the result is returned immediately, and codes must stay identical to the source. It stops short of describing failure modes or partial-state behavior.

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

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

Three dense sentences, all front-loaded with the action and outcome before the constraints. Every clause carries a distinct, useful instruction 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?

An output schema exists, so return values need no explanation. The description covers purpose, workflow, constraints, and the follow-up tool, leaving nothing an agent needs in order to invoke it correctly.

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

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

Schema coverage is 100% and the language enum plus 'must differ from primary language' are documented in the schema. The description adds the uniqueness rule (one translation per language) that the schema does not state, giving genuine extra 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?

States a specific verb and resource ('Add a language version (translation) to a form') and describes the concrete outcome (clones source text as draft). It explicitly distinguishes itself from siblings update_form_translation, list_form_translations, and the primary form, so an agent can route correctly.

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

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

Gives explicit when-to-use instructions plus a workflow sequence (create here, translate in place, save with update_form_translation). It also states two hard constraints: the language must differ from the primary language, and at most one translation per language, pointing to list_form_translations to verify.

Agents often have multiple tools that could apply. Explicit usage 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 clearly states this is a destructive/state-changing operation ('delete', 'move to trash', 'auto-purged'), but the annotations declare readOnlyHint: true. This is a direct annotation contradiction, so the behavioral transparency score must be 1.

Agents need to know what a tool does to the 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 sentences front-load the action, then explain recovery and permissions. No filler, and each sentence adds operational value.

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

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

Covers the action, recovery window, restore alternative, and permission model, which is complete for a soft-delete tool. The contradictory readOnlyHint makes full coherence slightly less complete, but the textual description itself is thorough.

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

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

The schema fully documents the only parameter formId as a UUID, so the description adds little about parameters. The described team/owner context is about authorization rather than the parameter's 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 action ('Move a form into the trash / soft delete') on a specific resource (form) within a context ('current team'). It lucidly distinguishes this soft-delete operation from a hard delete and names the recovery path via restore_form, making the tool's purpose unmistakable against siblings like delete_form_translation.

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

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

It gives clear invocation context: soft-delete rather than permanent removal, recoverable within 5 days before auto-purge, and explicitly points to restore_form as the undo path. It also states the authorization boundary (form owner or team owner/admin). It does not mention when to prefer duplicate/delete_form_translation, but that is not necessary for this tool's core use.

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

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

Annotations already mark this as destructive, but the description adds meaningful behavioral details: submission records are anchored to the source form and not deleted, and reports for historical records in the deleted language fall back to source text. It also notes the primary language cannot be deleted, which is a significant constraint. These go beyond the annotations and inform 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?

Three sentences with no redundancy. The purpose is front-loaded, the behavioral consequences are stated concisely, and the constraint about the primary language is clear. Every sentence adds value and there is no filler.

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

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

For a simple delete operation with an output schema present and annotations covering destructiveness, the description covers the key caveats: submissions are preserved, reports fall back, and primary language is excluded. It does not address potential errors (e.g., deleting a nonexistent language) or idempotency, but these are minor for this tool's complexity. Overall it is nearly 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 descriptions for both formId and language are sufficient (100% coverage). The description does not add extra parameter semantics; it only restates that a language is being deleted and mentions the primary language restriction, which is not directly tied to the parameter details. Baseline 3 is appropriate.

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

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

States the action clearly: 'Delete one language version (translation) of a form.' The resource is specific (a translation of a form), and it distinguishes itself from deleting the whole form (delete_form) and from other translation tools (create/update/get) by focusing on removal. It also clarifies the primary language cannot be deleted, which further scopes the purpose.

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

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

The description provides context for when to use this tool by stating what it deletes (a translation, not the source) and that the primary language cannot be deleted this way. It implies that other tools handle the primary language or whole form deletion, but does not explicitly name alternatives like delete_form or update_form_translation. This is clear but not fully explicit about 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?

Annotations already declare destructiveHint=true and openWorldHint=true, so the description correctly spends its words elsewhere: it discloses that deleting the last element is permitted (a form can be emptied) and, importantly, that {{code}} references are stripped from report.aiReport.instructions in the ai_quiz scene. That is exactly the kind of non-obvious side effect an agent needs before calling a destructive tool.

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

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

Three short sentences, front-loaded with the core action, then the edge case, then the side effect. No filler, though the mid-sentence type enumeration makes the first sentence slightly dense.

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

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

For a two-parameter destructive tool with an output schema, the description covers what gets removed, the empty-form edge case, and cross-entity cleanup. Missing only failure modes (e.g., unknown code) and whether the form must be in a draft/editable state.

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

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

Schema coverage is 100%, so both parameters are already documented; the description adds only that deletion is keyed by code and scoped to a form. No format, uniqueness, or error semantics for code are added beyond the schema.

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

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

States a specific verb (delete) and the precise resource (a single item identified by code), and enumerates the item kinds it applies to (question, Breaker, Statement/Swiper). This clearly separates it from delete_form (whole form) and update_question (modify rather than remove).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'single item by code' framing implies it is not the whole-form delete and not a modification, but no sibling is named and no explicit when/when-not guidance is given. The ai_quiz note hints at a conditional context but is framed as a behavior, not a usage rule.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description goes far beyond by listing what is NOT copied (submissions, sharing, integrations, ban state), noting fresh share links and your ownership, and flagging non-idempotency with a concrete failure mode. That timeout/retry warning is exactly the behavioral context annotations cannot convey.

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

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

Three tight sentences: what it does, what it excludes, and how to handle failure. Scope and exclusions are front-loaded, and the retry caveat is placed last where it belongs. 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?

An output schema covers return values, and the description already handles the remaining unknowns for a mutation tool: copy scope, ownership, side effects, and safe retry behavior. An agent has everything needed to call this correctly and to recover from a timeout.

Complex tools with many parameters or behaviors need more documentation. 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 itself documents newTitle's default and sourceFormId's UUID type, so the baseline is 3. The description adds conceptual context (the copy is owned by you with fresh share links) but does not elaborate on either parameter beyond what the schema states.

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

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

Opens with a specific verb+resource ("Duplicate a form") and immediately scopes it ("in the current team"), then enumerates exactly what is cloned: structure, scoring, report, visual settings, translations. This clearly separates it from create_form and create_form_from_template, which produce a form from scratch rather than copying an existing one.

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

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

Gives a concrete use case ("cloning a proven quiz and tweaking it") and an explicit retry protocol ("check first, then retry only if it is really missing"). It stops short of naming alternatives like create_form_from_template or create_form, so an agent must infer when duplication beats template creation.

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

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

Annotations already indicate this is a mutating, non-destructive operation. The description adds meaningful side-effect context: it verifies the object in storage, records it in the media library, and returns a media id + public URL. Failure modes and auth requirements aren't detailed, but the core behavior is well disclosed.

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

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

Three compact, front-loaded sentences with no filler. The critical timing constraint is stated immediately, and the next-step guidance is presented efficiently.

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

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

With a rich output schema, fully documented parameters, and a description that covers workflow position, side effects, and downstream usage, an agent has everything needed to invoke the tool correctly and understand its result.

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

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

The input schema already documents all 4 parameters with good descriptions at 100% coverage. The description reinforces that key, filename, and mimeType come from the prepare step, but adds limited 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 clearly identifies this as step 2 of a 2-step upload flow, specifying the exact action (verify, record, return media id + public URL) and distinguishing it from prepare_image_upload and update_form. An agent can immediately understand what this tool does and how it fits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states when to call this tool ('AFTER you have PUT the file to the uploadUrl') and what to do next ('call update_form with flagImg or landingImage'), providing clear sequencing and pointing to the relevant sibling 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?

Beyond the readOnlyHint annotation, the description reveals important operational behavior: the tool reports examineeSignupDisabled and what that flag means in practice, including its impact on login-required quizzes. It also communicates the implicit 'active tenant' state, adding value beyond the 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?

The description is front-loaded with the core purpose, then adds the flag explanation and a practical caution. Every sentence contributes valuable information; the length is justified by the important operational nuance it conveys.

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

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

The description fully covers what the agent needs: what the tool returns, why it matters, and the key flag to inspect. Combined with the output schema and read-only annotation, nothing critical is missing for an agent to call and interpret this tool correctly.

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

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

The tool has zero parameters and the schema already covers this completelyheb; the description adds no parameter details because none are needed. It provides meaningful context about what the returned data represents, which is more useful than mere schema confirmation.

Input schemas describe structure but not intent. Descriptions should explain 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 'Return' and the resource 'team (tenant) this token is currently operating against,' with the additional scoping note that all write tools default to this tenant. This makes the tool's purpose unambiguous and implicitly distinguishes it from tenant-switching tools like switch_active_tenant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 concrete contextual usage: it explains that this is the token's operating context, that write tools default to it, and specifically advises checking the examineeSignupDisabled flag before attributing sign-in problems to a quiz. It doesn't explicitly enumerate when not to use it, but the usage context is clear enough.

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

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

The annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by stating that customData is included and that sensitive auth fields are never returned, which goes beyond the structured annotations.

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

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

The description is two tight sentences with no filler. The core action and parameter are front-loaded, and the additional clarifications (a.k.a. respondent, customData, sensitive fields) each add relevant information without redundancy.

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

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

This is a simple one-parameter read tool with an output schema and safe annotations. The description covers scope, identity of the parameter, what is returned, and what is intentionally omitted. Nothing essential for calling the tool correctly is missing.

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

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

Schema description coverage is 100%, and the schema already explains examineeId as 'The examinee business ID (e.g. AB1234567890), as shown in list_examinees'. The description largely repeats this information, adding only the 'current team' scope, so it does not meaningfully enhance the parameter semantics beyond the schema.

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

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

The description uses a specific verb ('View'), identifies the resource ('one examinee'), and specifies the lookup key ('examineeId'). It also clarifies scope ('in the current team') and content ('including customData'), making it clearly distinct from sibling tools like list_examinees and update_examinee.

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

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

The description makes the intended use clear: retrieve full details for a single examinee by business ID, with the additional hint that the ID is the one shown in list_examinees. It does not explicitly name alternative tools or exclusion conditions, so it stops short of a 5, but the context 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 already declare this as a read-only, non-destructive, closed-world operation, so the description does not need to restate safety. It adds useful behavioral context by stating that the result includes fields[] and report configuration, that outcome codes live at report.outcomeAnalysis.outcomes, and that translationLanguages lists non-primary versions. It does not address missing-form behavior or permissions beyond 'current team.'

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

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

The purpose is front-loaded in the first sentence, and the remaining sentences focus on useful output details for outcome forms and languages. The description is appropriately sized for a read-by-id tool, though some return-value detail overlaps with the output schema.

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

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

Given rich annotations, 100% schema coverage, and an output schema, the description is complete enough to call the tool correctly. It covers the main return nuances and the current-team scope, but does not mention error behavior when a form is not found or inaccessible.

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

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

Schema description coverage is 100%, so the schema already documents id, includeFields, and includeReport fully. The description mentions the fields[] and report data that those booleans control, but it does not add syntax, constraints, or selection guidance beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'View one form of the current team in full.' It distinguishes the operation from list-style siblings by specifying a single form and enumerating the included data (fields[], report configuration). It stops short of naming an explicit alternative, so it is clear but not maximally differentiated.

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

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

The phrase 'View one form' implies usage when a single form's full details are needed, and the mention of large-form behavior is left to the schema. However, the description does not explicitly say when to use this tool versus list_forms, get_form_translation, or get_form_stats. Usage is therefore implied rather than stated.

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

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

Annotations already mark it read-only and non-destructive; the description reinforces this by saying 'Read' and adds useful behavioral context—telemetry source, current-team scope, stage semantics, and the special counting rule for leadCaptured. It does not undermine or 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 definition is front-loaded with the core action and resource, and both sentences carry useful information. The first sentence is dense and somewhat run-on, but the details are relevant enough to justify their inclusion.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema present, the description need not explain return values, and it covers the data source, stages, channel breakdown, counting caveat, and intended use. Minor ambiguity in 'embedded flag' and the lack of explicit cross-references to sibling tools keep it from being fully complete.

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

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

Schema description coverage is 100%: both formId and days are already documented with types, defaults, and bounds. The description only mirrors these as 'last N days,' adding little beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Read the conversion funnel for a form') and enumerates the exact metrics returned—stages, per-channel funnel, UTM combos, and drop-off points. The stage order and the leadCaptured counting nuance make it unambiguous and readily distinguishable from sibling stats/retrieval tools like get_form_stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states the intended use ('Use this to find where respondents drop and improve conversion'), telling an agent when to prefer this tool. It does not name alternative tools or exclusion conditions, so it stops short of full when/not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the domain serving check answers whether the form is live, the delivery settings reveal whether the form will accept responses, and utmSource tagging propagates across every link and snippet. It does not mention auth requirements or rate limits, so it stops short of a 5.

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

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

Front-loaded with the returned artifacts, then the utmSource behavior, then the routing to update_form_settings. Dense but every clause carries information; the only mild cost is a long first sentence enumerating outputs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 read-only 4-parameter tool with an output schema, the description supplies exactly the missing context: what the payload is for, how a parameter changes the payload, and which sibling performs the write. Nothing an agent needs before calling is absent.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning: passing utmSource tags 'every link and snippet' for one channel, which goes beyond the per-parameter schema text. The iframe and popup parameters are left to the schema, which documents them well.

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

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

States a specific verb (get) and resource (form share info) and enumerates exactly what comes back: public answer link per language, custom domain and serving status, embed snippets in three modes, and current delivery settings. An agent can distinguish this from get_form (definition) or get_form_stats without inspecting 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?

Explicitly names the use cases ('give me the link / the embed code', sanity-check a launch) and routes the mutation case to the sibling: 'change the switches with update_form_settings.' Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety profile is covered. The description adds useful context about the read scope (current team, time window) and the variety of statistics returned, but does not disclose any additional behavioral aspects (e.g., potential latency, data freshness, or auth requirements). Given the annotations cover the main safety concerns, the description adds moderate value.

Agents need to know what a tool does to the 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, information-dense sentence that front-loads the key action and scope, then uses a colon to introduce a list of the included statistics. While long, each item adds substantive value and there is no redundancy. It is efficiently structured without extraneous filler, but could potentially be split into two sentences for readability without losing 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?

The description comprehensively lists all the types of statistics returned, states the scoping to the current team and time window, and gives an explicit use-case ('gauge how a quiz is performing'). Given that an output schema exists (which would describe the response shape), the description covers the semantic context well. It does not mention edge cases like empty datasets, but these are unlikely to be required for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% – both parameters ('formId' and 'days') are fully documented in the schema. The description merely references 'over the last N days' without adding any new meaning, and does not clarify parameter syntax or relationships beyond what the schema provides. Baseline of 3 applies per the rubric.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Read submission statistics for a form') with specific scope ('in the current team over the last N days') and enumerates the exact data dimensions returned (KPIs, daily trend, channels, UTM combos, login types, device breakdown, per-question distributions). It is specific enough to distinguish from related siblings like get_form_funnel or get_form without 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?

The description explicitly says 'Use this to gauge how a quiz is performing and to suggest improvements,' providing clear context for when the tool is appropriate. However, it does not explicitly mention any alternative tool or state when NOT to use it, so it lacks direct comparison with siblings like get_form_funnel. It provides strong guidance but no exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes further by disclosing the error behavior when the language version is absent and by conveying the read-then-mutate workflow with its constraints (edit text, keep codes identical). It does not cover rate limits or pagination, which for a single-record read is minor.

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

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

Three sentences, each earning its place: what it returns, how to use it in the translate workflow, and the failure condition with the remedy. The purpose statement is front-loaded and nothing is padded.

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

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

With an output schema present, return values need no explanation, yet the description still summarizes the payload shape and flags the error case plus the follow-up tool. An agent has everything needed to call it correctly and act on the result.

Complex tools with many parameters or behaviors need more documentation. 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 enum is documented, so baseline is 3. The description adds genuine meaning tied to the language parameter: it must already exist, otherwise the call errors and you must create it first. No syntax details beyond the schema are added, but the precondition is a real semantic gain.

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

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

States a specific verb and resource ('Read the full content of one language version (translation) of a form') and even names what the payload contains (mirrored fields[] and report). This is clearly distinguishable from get_form and list_form_translations.

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

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

Gives an explicit workflow: use this to fetch the current draft before translating, edit text in place, keep codes identical, then save with update_form_translation. It also states the precondition for failure and names the sibling that fixes it (create_form_translation). Alternatives and when-not conditions are both covered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: results are scoped to the current team, all extra data (submissions, comments, change timeline) is opt-in, and lookup must never use a masked email. Return-value details are left to the output schema, which is appropriate.

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

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

The description is two sentences with no filler. The first sentence front-loads the primary purpose and result contents; the second covers optional inclusions and the critical lookup rule. Every clause earns its place and the structure supports quick comprehension by an agent.

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

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

For a read-only tool with a rich output schema and fully described parameters, the description is complete: it names the identifier, scopes the query to the current team, explains the optional expansions, and warns against the masked-email anti-pattern. An agent has everything needed to call this tool correctly without further inference.

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

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

Schema coverage is 100%, so the schema already documents all four parameters well, giving a baseline of 3. The description adds value by translating the boolean flags into the exact content they include (submission history, internal comments, change timeline) and by emphasizing the leadId/examineeId reference rule. This is useful extra semantic guidance, though the schema already carries the core 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 opens with a specific verb and resource: 'View one lead of the current team by leadId.' It then enumerates the payload contents (follow-up status, assignee, tags, respondent block, next booking), making it unambiguous what this tool returns and clearly distinct from list-oriented or examinee-focused siblings. It leaves no doubt that the resource is a single lead, not a record or examinee.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 contextual guidance: the lead must belong to the current team, and lookups must use leadId/examineeId rather than a masked email. It also clarifies the optional include flags behavior. However, it does not explicitly state when to prefer get_lead over sibling tools like get_examinee or list_leads, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a closed-world scope, so the safety bar is low. The description still adds genuine behavioral context beyond them: results are scoped to 'the current team', the report is a 'frozen' snapshot, and email/phone values inside answers come back masked.

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

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

Two sentences, front-loaded with the core action and scope, followed by the payload contents and then the masking caveat. Nothing is repeated and every clause carries information.

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

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

An output schema exists, so return-value documentation is not strictly required, yet the description still summarizes the payload shape, states the team scoping, and discloses the masking transformation. Combined with annotations covering safety, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and the single recordId parameter is fully documented in the schema; the description restates the same provenance ('the `id` field returned by list_records') without adding format, validation, or failure semantics. Baseline 3 is appropriate for a one-parameter tool whose schema does the work.

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

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

States a specific verb (view) and resource (one submission record / lead by record id) and enumerates exactly what is returned: examinee, answers, UTM metadata, frozen report result. This clearly distinguishes it from list_records, which only yields ids, so an agent can pick it without opening the schema.

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

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

Implies usage context by pointing at 'the `id` field returned by list_records', which tells the agent this is the fetch-one follow-up to a list call. However, it offers no exclusions or alternatives, and the sibling set contains get_lead and get_examinee whose relationship to this tool is never disambiguated despite the description equating 'record' with 'lead'.

Agents often have multiple tools that could apply. Explicit usage 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, destructiveHint=false, openWorldHint=true, and the description goes well beyond them: plan caps (Free 50 questions, ai_quiz 20 on every plan, what counts toward the limit) and an explicit non-idempotency/timeout-duplicate warning. Only gap is no mention of auth scope or what happens to existing codes/outcomes on insertion.

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

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

Front-loads the core action, then insertion referencing, then plan limits, then the idempotency caveat — a sensible order with every sentence carrying operational weight. The plan-limit passage is the densest part and could be slightly tightened, but nothing is filler.

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

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

Output schema exists so return values need no explanation, and the description covers the high-risk unknowns (limits, non-idempotency, reference semantics). For a 32-parameter tool it still relies on cross-referencing create_form for per-type field rules, which is a reasonable but not fully self-contained design.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: before/after must be mutually exclusive and must hold a field code from get_form, and Breaker/Statement/Swiper semantics (display-only, no answer) are stated. It still defers all per-field semantics to create_form questions[], so the caller must resolve a pointer.

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

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

Specific verb+resource ('Insert an item at a specific position') plus an explicit enumeration of the three item families (question, Breaker, Statement/Swiper). It clearly separates itself from add_question and create_form by positioning the tool as mid-insertion by reference code.

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

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

Gives concrete routing rules: use after/before with a code from get_form's field.code, front insertion by referencing the first field's code, and 'To insert at the end, use add_question' — naming the sibling and the condition that selects it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds valuable context beyond these: it explains the side effects ('pending membership is created immediately and an invitation email with a join link is queued'), the fact that the link/token is never returned, and role restrictions. This goes beyond the annotations to set accurate expectations, 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 longer than minimal but every sentence carries essential information: action, side effects, restrictions, failure conditions, and contextual preparation. It is front-loaded with the core purpose and then expands logically. While it could be trimmed slightly, the density of useful content justifies the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 side effects and role-based restrictions, the description covers all necessary aspects: when to use it, prerequisites, failure modes, and the non-return of sensitive data. An agent can correctly invoke this tool without needing to infer anything beyond what is stated, making it fully complete for its 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 coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds value by clarifying the meaning of each role enum value: 'viewer' is read-only, 'admin' manages the whole team, and 'owner' is explicitly excluded. It also confirms the default for 'role'. This enhances the schema without redundancy.

Input schemas describe structure but not intent. Descriptions should explain 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 and resource: 'Invite someone to the active team (tenant) by email.' It specifies the exact scope and distinguishes it from sibling tools like switch_active_tenant and list_my_tenants by focusing on the invitation action. The verb 'invite' and object 'team' are precise, making the tool's purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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, including role requirements ('Only the team owner or an admin can invite'), failure conditions ('Fails if the email is already a member...'), and how to prepare the correct context ('use list_my_tenants / switch_active_tenant to change teams first'). This is comprehensive and leaves no ambiguity about when or how to invoke the tool.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the safety profile is covered; the description nonetheless adds non-obvious behavior – the two provider sources, that reschedules/cancels in Cal.com propagate back, and that attendee name/email are returned masked. The masking disclosure in particular is operationally important and appears nowhere in the annotations.

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

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

Effectively front-loaded: the core action and ordering come first, filters and identifiers follow. The second sentence carries a long parenthetical about providers and a full field inventory, which is useful but slightly overpacked relative to the rest.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema, full parameter descriptions and annotations available, the description supplies the parts structured data cannot: data provenance, sync direction, and result masking. The remaining gap is minor – page/limit behavior is left entirely to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents from/to/status/formId/recordId/examineeId precisely, including the pending vs scheduled status meanings. The description recaps the filter dimensions and the 'reference by bookingId' convention but adds no format or edge-case detail beyond the schema.

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

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

Opens with a specific verb and resource plus scope: 'List the bookings of the current team, earliest first.' It goes further than the name by defining what a booking actually is here – Cal.com-synced bookings plus read-only history from the retired native scheduler – which is information an agent cannot infer from the title.

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

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

Gives clear operating context: it is read-only, changes made in Cal.com sync back, and results can be narrowed by status/quiz/respondent/time range with bookingId as the reference key. It does not state when a different tool should be used instead, but no sibling in the list covers bookings, so there is no real routing ambiguity to resolve.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses that sensitive auth fields are never returned, the examineeId is returned unmasked, and the listing is scoped to the current team. These details give an agent a clear expectation of the data and behavior.

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

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

The description is concise and front-loaded: two sentences that first state the core purpose, then provide supplemental context (sensitive fields, examineeId unmasking, pointer to get_examinee). Every sentence adds distinct value 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?

With an output schema present, the description covers the essential operational context: team scope, ordering, sensitive field omission, and the relationship to get_examinee. Nothing an agent needs to invoke the tool correctly is missing.

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

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

The input schema already documents all three parameters with descriptions (limit with default/max, search as fuzzy match, status as enum). The description adds no additional parameter-specific meaning, so 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 clearly states the verb (list), the resource (examinees/respondents), the scope (current team), and the ordering (newest first). It explicitly distinguishes from get_examinee by naming the alternative for full detail, so an agent can select the right tool without 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?

The description gives explicit when-to-use guidance: 'Use get_examinee for one examinee's full detail including customData.' It also notes that the examineeId is what get_examinee/update_examinee take, which helps an agent decide between listing and retrieving a single record.

Agents often have multiple tools that could apply. Explicit usage 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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral detail: results are ordered reverse-chronologically by creation and omit question content, which agents cannot infer from the schema. Pagination behavior is left to the schema's limit field.

Agents need to know what a tool does to the 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, with the resource scope front-loaded and the ordering/content caveat immediately after. The sibling pointer is placed last, where the agent needs it.

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

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

With annotations covering safety, a 100%-covered schema, and an output schema for return shape, the description only needed to supply ordering and content-scope context, which it does. Minor gap: it never hints that the endpoint is filterable, so an agent skimming only the description might not think to narrow results.

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

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

Schema description coverage is 100%, so limit, scene, and titleContains are all documented with types, defaults, and enum values. The description adds nothing about the semantics of these filters, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the forms of the current team') and scopes it to the current team, which distinguishes it from the many form-related siblings such as get_form and list_templates. An agent can tell immediately what this returns.

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

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

Explicitly routes the agent to get_form when question content is needed, which is a real alternative with a clear selection condition. It does not discuss when to reach for the filter parameters versus paging through results, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns each translation's language, isActive flag, public share link, and timestamps, and clarifies that the primary language is excluded. This goes beyond the annotations and helps the agent understand the result set.

Agents need to know what a tool does to the 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 fluff. The first sentence states the action and the return fields; the second clarifies an important edge case (primary language not included). 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 tool has a single required parameter, a full output schema, and annotations covering safety. The description explains what is returned and what is excluded. It could mention pagination or ordering, but for a simple list operation with an output schema, this is nearly complete.

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

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

Schema description coverage is 100%: formId is described as 'The source form UUID'. The description doesn't add much beyond that, but it does imply that formId identifies the form whose translations are listed. Baseline 3 is appropriate since the schema already documents the parameter fully.

Input schemas describe structure but not intent. Descriptions should explain 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 lists existing language versions (translations) of a form, and explicitly distinguishes it from get_form by noting the primary language is not included. This differentiates it from siblings like get_form_translation and create_form_translation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an overview of all translations of a form. It also clarifies that the primary language is handled elsewhere (get_form.language), which helps an agent avoid using this tool for the primary language. It doesn't explicitly name alternatives like get_form_translation, but the context is clear enough.

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

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

Even though readOnlyHint=true and destructiveHint=false already cover the safety profile, the description adds non-obvious behavior: leads are aggregated per respondent across all forms, newest activity first, and the hasUpcomingBooking filter applies within the page so counts remain unfiltered. That is real behavioral disclosure 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?

Four sentences cover the core behavior, default ordering, filter dimensions, and an important lexical rule. It is compact and front-loaded with the main action. It could be split into a more scannable format, but nothing is wasted.

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

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

For a read-only, 10-parameter listing endpoint with an output schema, the description covers the essential semantics (one lead per user, default ordering, filter options, team-defined codes) without re-heating the schema. It does not over-explain return fields, which is fine given the output schema exists. A little more about pagination behavior would round it out.

Complex tools with many parameters or behaviors need more documentation. 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 describes all 10 parameters (100% coverage), so the requirement is low. The description still adds value by explaining the identity rules ('reference a lead by leadId, a respondent by examineeId'), clarifying the team-defined vocabulary, and noting keyword search works against unmasked server-side values. Good but not essential.

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

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

The description opens with a clear verb and resource ('List the leads (CRM records)') and immediately sharpens the meaning: one lead per respondent across all forms, with specific fields carried. This distinguishes it from sibling list tools like list_records and list_examinees, so an agent can tell what makes this endpoint unique.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 gives a prerequisite: 'call list_lead_settings first' to obtain valid status/tag codes and warns 'never guess.' That is solid procedural guidance. It does not, however, spell out when to pick list_leads over other list variants (e.g., list_records or list_examinees), so it falls just short of full score.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly aligns with those. It adds value beyond the annotations by explaining that the tool returns team-specific configuration and that the returned values are required for successful write operations. It doesn't contradict annotations and gives useful context about the tool's role in the workflow, though the output structure is left to the output schema.

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

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

The description is two sentences with no redundancy. The first sentence states the core purpose and enumerates the returned items; the second sentence gives critical usage guidance and rationale. It is front-loaded with the primary action and uses every word effectively, exceeding the minimum necessary 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 parameters, has an output schema (as indicated in context signals), and annotations cover read-only and non-destructive behavior, the description is fully sufficient. It explains what the tool returns, why it should be called before specific write tools, and the team-specific nature of the data. An agent can call this tool correctly without any additional information beyond what the schema and annotations already provide.

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

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

The tool has zero parameters, so there is nothing to explain. Baseline for 0 params is 4, and the description doesn't mention parameters at all, which is appropriate. It focuses entirely on the return value and usage context, not requiring any 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 clearly states it reads the team's lead configuration, enumerating the specific elements (status codes with label/colour, colour tag library, assignable members). It uses an explicit verb ('Read') and resource ('lead settings'), and differentiates itself from sibling write tools by framing itself as the prerequisite read for update_lead, set_lead_tags, and assign_leads. This makes 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 explicitly instructs to 'Call this before update_lead / set_lead_tags / assign_leads' and explains why: status codes, tag codes, and member ids are team-specific, and write tools reject unknown values. This provides clear when-to-use guidance and implicitly states when not to use it (no need to call for other purposes). It also points to alternative write tools that require this information.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious context by scoping results to the current user's memberships and explaining the isActive flag, which goes beyond the 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 tight sentences deliver purpose, scope, and key field semantics with zero waste. The most important information comes first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 parameters, a read-only annotation, and an output schema present, the description fully covers what an agent needs to call the tool correctly. It even clarifies the ambiguous tenant/team terminology and the isActive field.

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

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

The tool has zero parameters, and the schema coverage is trivially 100%. Per the baseline for parameterless tools, a 4 is appropriate; there is no param info needed and the description adds relevant semantic 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?

States a specific verb ('List') and resource ('all teams (tenants) the current user belongs to'). The isActive clarification further distinguishes this from get_active_tenant and switch_active_tenant, making the 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?

Provides clear context about scope ('current user belongs to') and the meaning of isActive relative to the active token. It does not explicitly name alternatives or when-not-to-use, but the context is enough to infer appropriate usage.

Agents often have multiple tools that could apply. Explicit usage 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 readOnly/non-destructive, and the description adds behavior beyond them: newest-first ordering, default page size via schema, and critically that emails and phone numbers embedded in answers come back masked. That masking disclosure materially changes how an agent should interpret results and is not derivable from the annotations.

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

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

Front-loaded with purpose and scope, and every sentence carries signal (ordering, item contents, filtering, masking caveat, sibling routing). Slightly dense and the item-contents sentence partially duplicates the existing output schema, but nothing is wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema covering return shape, full schema descriptions, and annotations covering safety, the description supplies the remaining pieces an agent needs: ordering, filtering dimensions, masking behavior, respondent reference rule, and the sibling hand-off to get_record.

Complex tools with many parameters or behaviors need more documentation. 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 (page, limit, since/until, formId, status) is documented in the schema itself, including the awaiting_gate enum meaning. The description only restates the filter categories rather than adding syntax, defaults, or edge cases, so baseline 3 applies.

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

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

States a specific verb and resource ('List submission records (leads) of the current team'), plus scope, ordering ('newest first'), and item shape. An agent can distinguish it from get_record and from generic list tools without opening the schema.

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

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

Explicitly routes to the alternative: 'Use get_record for one record's full detail', and gives a usage rule for respondent lookup ('reference by examineeId, never by a masked email'). Clear context, but it does not differentiate from other list siblings such as list_leads or list_examinees, which an agent may also weigh.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds behavioral context: it filters to 'active templates' and orders by 'most-used first', which is useful for understanding the result set. It does not go into pagination details, but the annotations plus description cover the essential behavior without contradiction.

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

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

The description is two sentences long with no filler. The first sentence states the purpose, output fields, and ordering; the second sentence gives a direct workflow pointer to the next tool. It is front-loaded and every word earns its place.

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

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

Given the tool's simplicity, the presence of an output schema, annotations that declare read-only safety, and a fully documented parameter schema, the description covers all necessary context. It tells the agent what to do, why, and how to follow up, making it complete for correct invocation.

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

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

All five parameters are fully documented in the schema with descriptions (100% coverage), so the schema already provides the necessary meaning. The tool description does not add extra parameter details beyond what is in the schema, but it does mention the returned fields that relate to the output, which is a slight bonus. Baseline 3 is appropriate since the schema carries the heavy lifting.

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

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

The description clearly states the verb 'List' and the resource 'active templates in the public template library', enumerates the returned fields, and specifies the ordering. It also distinguishes from sibling list tools like list_forms by focusing on templates and explicitly connecting to create_form_from_template.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explicit guidance on when to use this tool: to find a template, and then directs the agent to call create_form_from_template with the template id. It also frames this as the fastest way to build a quiz when a suitable template exists, implicitly telling the agent to prefer this path over directly creating a form.

Agents often have multiple tools that could apply. Explicit usage 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 (mutation) and destructiveHint=false, so the description adds context about how the move works (after/before, front/end). It doesn't disclose potential side effects like reordering implications or error handling, but given annotations, the added value is moderate. 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, front-loaded with the main purpose and mechanism. It includes all essential information without redundancy or fluff. Each sentence contributes value, making it efficient and easy to parse.

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

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

The tool has a moderate complexity (moving items with after/before and front/end logic), and the description covers the core usage scenarios. An output schema exists, so return value details are not needed in the description. It doesn't mention edge cases like invalid codes or same-position moves, but for an agent, the provided guidance is sufficient to invoke correctly in common 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 100%, so all parameters are documented. The description adds meaningful semantics beyond the schema: it clarifies that 'after' and 'before' are mutually exclusive, and explains how to reference the first/last field for front/end moves. This enriches understanding of the parameters, especially the interplay between code, after, and before.

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

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

The description clearly identifies the verb 'move' and the resource 'existing item (question, page break or display block)' and specifies the mechanism (by code, referencing another field's code). It also differentiates from sibling tools like add_question, update_question, and delete_question by focusing on reordering, and gives explicit front/end usage. This 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 provides explicit usage instructions: choose either after or before, and explains how to move to the front (before the first field's code) or end (after the last field's code). It implies the tool is for repositioning existing items, which distinguishes it from add/update/delete. However, it doesn't explicitly state when not to use it or compare with alternatives, but the context is clear enough.

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

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

Annotations only mark readOnlyHint=false and destructiveHint=false, so the description carries the burden of behavioral disclosure. It adds substantial detail: the presigned URL is short-lived, uploads over 5MB are rejected, the team storage quota is checked up front, and the caller must send a matching Content-Type header. This fully explains side effects and constraints 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 long, but every sentence carries load-bearing operational information and the structure is a clear numbered workflow with concrete examples. The key behavioral fact (returns a presigned URL, does not accept bytes) is front-loaded. It is not minimal, but the length is justified by the complexity of the two-step upload.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 multi-step upload involving local temp files, compression, MIME constraints, size caps, quota checks, HTTP PUT semantics, and a follow-up finalization tool, this description is complete. It even includes cleanup and tells the agent exactly how to call the sibling next. Since an output schema exists, not describing return values in prose 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%, so the baseline is 3. The description adds operational meaning beyond the schema: fileSize is optional and refers to the file after compression, it is checked early against the 5MB cap and quota, and the authoritative size check happens in finalize_image_upload. It also clarifies that filename is for admin display and mimeType must match the uploaded Content-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?

States a specific verb+resource pair: prepares the first step of a two-step image upload and returns a presigned URL rather than accepting image bytes. Explicitly differentiates from finalize_image_upload by numbering itself Step 1 of 2, so an agent can distinguish it from the sibling without inspecting schemas.

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

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

Provides an explicit numbered workflow covering pre-upload compression, when to call this tool, when to PUT to the returned URL, and when to call finalize_image_upload. It also states what the tool does NOT do (receive image bytes), which prevents an agent from attempting a direct upload through this conversation.

Agents often have multiple tools that could apply. Explicit usage 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 permission requirements (owner/admin only), scope (current team), and failure behavior (errors if form is not in trash). This goes well beyond the readOnly/destructive hints and gives the agent concrete expectations.

Agents need to know what a tool does to the 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 front-loads the action ('Restore'), scope ('from the trash in the current team'), relationship ('undo delete_form'), access restriction, and error behavior. 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 one-parameter restoration action with an output schema and annotations present, the description covers what, where, who can perform it, and when it errors. There is no meaningful missing context for an agent to invoke it.

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

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

Schema coverage is 100% and the schema already describes formId as the form UUID. The description adds contextual constraints (must be in trash, current team) but does not add parameter-specific details beyond what the schema provides, so the baseline 3 applies.

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

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

The description begins with a specific verb and object: 'Restore a form from the trash in the current team'. It also explicitly frames the operation as

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

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

It explicitly names its counterpart 'delete_form', states the required context ('from the trash in the current team'), gives the permission prerequisites (owner/admin), and calls out an error condition when the form is not in the trash. This leaves little ambiguity about when the tool applies.

Agents often have multiple tools that could apply. Explicit usage 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 substantial behavior beyond annotations: the dimension list is replaced while omitted title/radar settings are kept, dimension codes are stable and preserved by name, an empty dimensions array clears the analysis, and a dimension still referenced by question dimensionScores or report.formula cannot be removed. These details clarify the destructive and open-world annotations with concrete preservation and constraint rules.

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

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

The description is front-loaded with the core purpose and scope, and every sentence conveys relevant constraints or behavior. It is somewhat dense and could be split for readability, but there is no filler or wasted text.

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

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

Given the tool's complexity, the available annotations, output schema, and full schema coverage, the description is complete: it covers prerequisites (get_form), supported form types, clearing behavior, code stability, formula constraints, and removal restrictions. An agent has enough information to invoke it correctly.

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

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

Schema description coverage is 100%, so the structured schema already documents all parameters thoroughly, including dimension code rules, formula syntax, and level semantics. The description adds some operational context about dimension code stability and formula requirements, but much of that information is repeated from the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: setting the multi-dimension analysis (form.report.dimensionAnalysis) of a form, with explicit scope that overallAnalysis is untouched. It distinguishes itself from overall settings and names unsupported form types, so an agent can tell what this tool does and does not do without opening the schema.

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

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

The description provides clear usage context: only scored_quiz forms have dimensions, it is not supported for knowledge_quiz / random_knowledge_quiz / outcome_quiz / ai_quiz forms, and callers should call get_form first. It implies the alternative (update_form for overall settings) via 'without touching overallAnalysis' but does not explicitly name a sibling alternative, keeping this just below the top score.

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

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

Annotations already flag destructive=true. Description adds concrete destructive semantics: replace overwrites the entire tag set, add/remove are selective, remove tolerates stale codes, and changes are recorded on each lead's timeline. This is valuable 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?

Tight, information-dense description with no filler; efficiently explains modes and caveats in a few sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 scope, batching limits, mode semantics, references the correct source of tag codes, and notes side effects (timeline). Nothing an agent needs to safely invoke it is missing.

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

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

Schema covers all parameters, but the description adds field-level behavior beyond the schema: mode-by-mode meaning, the single-call batching instruction, and the stale-code behavior for remove.

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

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

States a precise operation: setting colour tags on one or more leads in the current tenant, distinguishes itself from generic update_lead by scoping to tags and listing batch semantics. The verb, object, and scope are all explicit.

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

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

Gives clear operational guidance: pass every lead id in a single call (do not loop), and explains when to use replace vs add/remove. Does not explicitly route to an alternative tool, but gives complete usage context for the various modes.

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

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

Annotations mark readOnlyHint=false, and the description goes beyond that by disclosing persistence across sessions and the membership requirement. That is meaningful behavioral context for a state-changing token operation.

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

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

Two tightly written sentences convey operation, persistence, and a prerequisite with no filler. Key facts are 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 single-parameter state-change tool with an output schema and full schema coverage, the description is nearly complete. It could mention that get_active_tenant reveals the current team, but that omission is minor.

Complex tools with many parameters or behaviors need more documentation. 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 fully describes tenantId with 100% coverage and even points to list_my_tenants for discovery. The description adds no new parameter meaning, so the baseline 3 applies.

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

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

The description clearly states a specific action (switch) on a specific resource (active team/tenant) and explains the scope (for this token). It is immediately distinguishable from siblings like get_active_tenant and list_my_tenants.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 conveys when to use it (change active team) and includes the membership prerequisite. It does not explicitly mention siblings or exclusion criteria, but the context is sufficiently clear among the listed 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?

The description goes well beyond the destructiveHint annotation: it warns that customData REPLACES the whole object, that masked values are rejected, and that re-sending read values can wipe phone fields. This is exactly the kind of behavioral trap an agent must know before calling, and no annotation can convey it.

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

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

The description is dense but well-structured: it opens with the core action, then enumerates editable fields manageable size, and finishes with the high-risk customData warning. It is slightly long but every sentence earns its place; there is no filler.

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

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

For a moderately complex mutation with high-risk customData semantics, the description covers identification, editable fields, immutable fields, validation rules, and destructive pitfalls. It is complete enough that an agent can safely invoke the endpoint without hidden surprises. An output schema exists, so not re-describing return values 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?

Despite the schema parameter descriptions, the text adds critical semantics: customData replacement semantics, the validation rules (required/unique/type), and the immutable email/tenant fields. It also explains examineeId provenance. This far exceeds what the raw schema provides.

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

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

The description opens with a specific verb and target ('Update an examinee'), identifies the locating key (examineeId), and clarifies the scoped context ('in the current team'). It also names the source of examineeId (list_examinees), so an agent can determine what this tool does and on which resource without opening the schema.

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

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

It gives clear, actionable context: the examinee is found by examineeId from list_examinees廉, and it enumerates which fields are editable versus immutable (email, tenant, examineeId). It does not explicitly contrast with alternative update tools, but the usage context is strong enough to route an agent correctly.

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

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

Goes well beyond the destructiveHint=true annotation: it discloses merge-by-sub-key semantics, that "" clears a sub-key, that systemText is replaced wholesale, that an outcome referenced by question votes cannot be removed, and that language is only changeable while no language versions exist. These are exactly the mutation constraints an agent needs before calling a destructive write.

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

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

Front-loads the field inventory, then adds constraints in roughly the same order, with no filler sentences. It is one dense block rather than separated bullets, which costs some scannability for a description this long, but every clause carries information.

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

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

For a destructive 11-parameter tool with deep nested objects, the description covers scene-specific rejection rules, merge/clear semantics, prerequisite ordering, and cross-tool handoffs. With an output schema present and rich schema descriptions, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is already 100%, so the baseline is 3; the description adds non-schema semantics on top — which fields merge vs replace, what "" does, that flagImg is the quiz cover versus landingImage the landing-page cover and that the latter does not toggle the landing page. It stops short of explaining individual nested fields like report.levels/formula, which it defers to the schema.

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

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

Opens with a specific verb+resource ("Update a form of the current team") and enumerates exactly which fields are in scope, which also implicitly scopes out questions and dimensionAnalysis to their own tools. An agent can tell this apart from add_question / set_dimension_analysis without opening any schema.

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

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

Explicitly routes questions to add_question / update_question / delete_question / move_question and dimension analysis to set_dimension_analysis, and the report sub-key spells out the create_form-then-update_form workflow for auto-generated codes. It does not, however, distinguish itself from the sibling update_form_settings, which is a real ambiguity given both names imply form-level updates.

Agents often have multiple tools that could apply. Explicit usage 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 marking this as destructive, non-read-only, and open-world, the description explains concrete side effects: only passed keys change, slug changes break the previous path, feedback is replaced wholesale, PDF download is Pro-only, and crowdCompare is unavailable for knowledge quizzes. It adds substantial behavioral context rather than merely restating hints.

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

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

It is front-loaded with the key distinction and alternative tool, which is the right structure for a high-impact routing decision. It is longer than necessary because it re-enumerates many settings already documented in the schema, though the length is defensible given 14 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 complexity, nested objects, annotations, and output schema, the description is complete enough for correct invocation. It covers preconditions, key side effects, parameter interactions, and where to read current state.

Complex tools with many parameters or behaviors need more documentation. 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 parameters deeply. The description still adds useful business meaning, such as calling submissionAccess the lead-capture gate, explaining the completion-rate vs lead-quality tradeoff, and describing sharing as organic spread, though portions of the field list repeat 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 opens with a precise distinction: it changes how a form is delivered rather than what it says, and explicitly points to update_form for title/questions/report/theme. That lets an agent separate this tool from the closest sibling immediately.

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

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

It states the exact use case, names the alternative for content edits, and tells the agent to read current values with get_form_share_info before changing them. The when-to-use and when-not-to-use boundaries are explicit.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true. The description adds meaningful behavioral context beyond them: merge semantics ('fields you omit keep their current value'), validation ('must not introduce codes that do not exist on the source form'), and scoped pausing. It doesn't flag that some blocks (e.g. feedback) are replaced wholesale – that detail only lives in the schema.

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

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

Three dense sentences, front-loaded with the core action, then merge semantics, then the code constraint, then the isActive note. No padding and every clause carries an operational detail an agent needs.

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

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

Given 10 parameters, nested objects, a destructive annotation, and an existing output schema, the description covers the essential contract: source of the draft, partial-merge behavior, code validation, and scoped pausing. It leaves some nuances (per-block wholesale replacement like feedback) to the schema, which is acceptable but slightly incomplete for a destructive mutation.

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

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

Schema description coverage is high (100%), so the baseline is 3. The description still adds value by grouping which top-level keys to pass (title/description/fields/report/systemText/booking/feedback) and tying them to get_form_translation output, plus the isActive independence. That is real semantic value beyond field-by-field schema descriptions.

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

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

The description opens with a clear verb and resource: 'Save translated copy for one language version of a form', which tells the agent it is writing a per-language translation and not the source form. It does not name or distinguish itself from the sibling create_form_translation or delete_form_translation, so the agent must infer which call applies.

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

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

It gives concrete guidance: mirror the shape returned by get_form_translation, omitted fields keep current values, and partial translation is allowed. It also says to pass isActive=false to pause just that language. It stops short of explicitly stating when to use this vs create_form_translation, so an agent must infer the 'existing version vs new version' split.

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