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?

The description deliberately discloses the critical non-idempotency risk: 'if the call times out it may still have succeeded, so retrying blindly can create a duplicate — check first, then retry only if it is really missing.' It also clarifies which fields are ignored/rejected for various types and explains scene-specific behaviors, adding value well beyond the sparse functional 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 primary purpose is front-loaded with a single, clear opening sentence, and the paragraph is packed with genuinely useful type/scene information rather than filler. The information is dense and could have been split into bullets, but the length is justified by the tool's complexity and the schema descriptions do not repeat it verbatim in a bloated way.

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

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

Given the tool's complexity (28 parameters, multiple scenes and question types), the description covers side effects (non-idempotency), scene/type availability, and the 'configuration in the web app' boundary. An output schema exists, so the return value does not need to be described; nothing critical to safely invoking the tool appears to be missing.

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

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

Schema description coverage is 100% and each parameter already carries a thorough description, so the baseline is 3. The tool description does add a few non-schema facts (e.g., 'prefer DropDown over SingleCheck/MultiCheck past 20 choices', 'configure random question banks in the web app'), but it largely repeats the schema's field-applicability summary rather than contributing substantial new 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 opens with a specific verb and resource: 'Append an item to the end of a form,' which clearly distinguishes it from the sibling insert_question by emphasizing end-append semantics. It then enumerates the full range of item types it can create, so an agent knows exactly what the tool does and what is out of scope.

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

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

The description gives valuable selection guidance within the tool (e.g., 'prefer it over SingleCheck/MultiCheck past 20 choices', scene-specific restrictions like 'Cascade ... scored_quiz only'). However, it never mentions the tool-level alternative insert_question or states when to use add_question vs. insert_question; the advice to 'Configure random knowledge quiz question banks in the web app' is the only explicit workaround and covers only a narrow case.

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

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

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

Annotations convey write intent (readOnlyHint=false, openWorldHint=true) but carry little else. The description adds genuinely valuable behavioral disclosure beyond them: the tool is not idempotent ('if the call times out it may still have succeeded... retrying blindly can create a duplicate'), it creates only the primary language, and it requires outcomes at create time in the outcome scene. 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 long but front-loaded: the highest-value operational guidance (one-call creation, scene-specific requirements, idempotency warning) appears in the first sentences, with progressively more detailed notes after. For a 9-parameter tool with deeply nested objects, the density is justified — every sentence earns its place and none restate the schema.

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

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

Comprehensive for a tool of this complexity: it covers scene-specific creation requirements, the recommended multi-step workflow (create → read codes → update formulas), non-idempotency risk, and language handling, while pointing to sibling tools for follow-up. The output schema exists, so return values need no explanation. The only gap is not addressing the form-template path (create_form_from_template) as an explicit alternative.

Complex tools with many parameters or behaviors need more documentation. 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 goes beyond the schema by explaining scene-specific semantics (outcome_quiz requires report.outcomes; scored_quiz needs dimension formulas and can reference dimensionScores), and by describing the create-then-fill workflow where structuredContent.fields carries question codes that must be read before writing report.formula. This adds real meaning the schema's per-field descriptions do not.

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

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

The description opens with a specific verb+resource ('Create a form in the team this token is bound to') and immediately distinguishes the tool from its siblings by instructing the agent to pass questions and report config in one call 'instead of following up with per-question calls' — clearly routing away from add_question/insert_question. The one-call-create semantics set it apart from create_form_from_template, update_form, and create_form_translation 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?

Gives clear operational guidance: create everything in a single call, then fill in formulas via update_form / set_dimension_analysis afterward, and use create_form_translation for additional languages. It explicitly names translation as the alternative for non-primary languages. However, it never contrasts with create_form_from_template or clarifies when one would update versus create, so the exclusion guidance is partial.

Agents often have multiple tools that could apply. Explicit usage 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?

Beyond the annotations, the description discloses meaningful behavior: the tool clones the source text as an initial draft and returns it for immediate editing. It also surfaces constraints not fully visible in the schema, such as the one-translation-per-language uniqueness rule.

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

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

The description is compact and front-loaded with the purpose, then gives the workflow, then the constraints. Every sentence adds necessary information, and there's no empty or redundant phrasing.

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

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

With only two required parameters, an output schema, and annotations already present, the description covers enough for correct invocation and follow-up: purpose, constraints, return-as-draft behavior, and the next tool to use. The agent is fully equipped to call 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 description coverage is 100%, so the baseline is strong. The description adds useful meaning by framing formId as the source whose text is cloned and language as a value that must be unique per form, pointing to list_form_translations to verify validity.

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

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

The description names a specific verb and resource: adding a language version/translation to a form. It also differentiates itself from siblings by explicitly describing the clone-then-edit workflow and pointing to update_form_translation as a separate save step.

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

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

It gives clear context for when to use this tool: when adding a new translation, not editing an existing one. It directs the agent to list_form_translations for the at-most-one-per-language rule and to update_form_translation for saving edits, so the agent can choose 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?

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 readOnlyHint=false, so the description appropriately focuses on additional behavior: the types of items supported (including page breaks and display blocks) and the rule that deleting the last item is allowed. This adds context beyond the annotations and does not contradict 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 tightly written sentences with no redundancy. The purpose is front-loaded, the item types are listed, and the edge case (empty shell) is stated. Every word earns its place.

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

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

For a simple deletion tool with an output schema available, the description covers the scope of deletion, supporting item types, and the edge case of empty forms. It does not discuss error handling (e.g., missing code) but that is typically implicit. Overall, sufficient for an agent to call it correctly.

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

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

Schema coverage is 100% for both parameters (formId, code), so the schema already documents them fully. The description adds the hint that deletion is 'by code' (implying code is the unique identifier), which is a minor clarification but does not expand on format or constraints. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Delete') and resource ('a single item from a form by code') and clearly enumerates item types (question, page break, display block). It distinguishes from sibling tools like update_question, insert_question, and delete_form by scope (single item vs whole form).

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

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

The description implicitly defines usage by specifying exactly what it deletes and that deleting the last item produces an empty form. It does not explicitly name alternatives or state when not to use it, but the scoping to single items differentiates it from form-level deletion. Clear context, though no explicit exclusions.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint false), the description adds crucial behavioral context: the operation is non-idempotent and can silently succeed on a timeout, and it clarifies ownership changes (new form owned by you) and what data is intentionally excluded. This is exactly the kind of side-effect disclosure that annotations alone do not provide.

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

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

The description is compact yet comprehensive, with each sentence earning its place: core action, exclusions, use case, and a non-idempotency warning. The main verb and object are front-loaded in the first sentence, making the tool's purpose instantly recognizable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 present, the description covers all essential decision factors: what is cloned, what is not, the use case, and the retry caveat. Nothing an agent needs to safely invoke it is missing; the output schema handles return-value details.

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

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

Schema coverage is 100%—both sourceFormId and newTitle are fully described in the input schema. The description adds no additional parameter-level meaning, so the baseline of 3 applies. It doesn't need to compensate for any schema gaps.

Input schemas describe structure but not intent. Descriptions should explain 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-resource pair, 'Duplicate a form in the current team,' and enumerates exactly what is cloned (structure, scoring, report, visual settings, translations) and what is not (submissions, sharing, integrations, ban state). This clearly distinguishes it from siblings like create_form or create_form_from_template, which create new forms from scratch or templates.

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

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

It provides a concrete use case—'cloning a proven quiz and tweaking it'—which tells an agent when to reach for this tool. It does not explicitly name alternative tools or give a when-not-to-use rule, but the scope of duplication versus creation is unambiguous from the purpose statement, so the guidance is adequate.

Agents often have multiple tools that could apply. Explicit usage 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavior beyond that: it reports enabled:false when booking is off or not in the plan, excludes the current slot when a bookingId is passed, warns that invalid start times are rejected, and discloses server-side range clamping. 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?

Four dense sentences, each earning its place: purpose and computation, special return value, rescheduling workflow and rejection behavior, and range clamping. The main purpose is front-loaded and there is no filler or repetition of schema content.

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

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

Given that an output schema exists and read-only annotations already cover safety, the description covers all necessary invocation context: availability computation, enabled:false handling, bookingId semantics, the precondition for reschedule_booking, and server-side range limits. Nothing essential for a correct call 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 documents all three parameters. The description reinforces bookingId's role by explaining the current slot is 'not counted as taken', but it adds little beyond the schema's own description for that parameter and nothing new for fromDate/toDate. This meets the baseline without exceeding it.

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

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

The description opens with a specific verb and resource: 'Read the current team's bookable time slots in a date range'. It further distinguishes the tool from siblings like list_bookings by explaining slots are 'computed from the team's weekly booking rules minus what is already taken', making the availability concept 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 gives explicit guidance: pass bookingId for rescheduling and 'always call this before reschedule_booking' because an out-of-range start time is rejected. It does not explicitly state when to prefer list_bookings or other sibling tools, but the availability-versus-bookings distinction is sufficiently clear for routing.

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

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

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 readOnlyHint=true and destructiveHint=false, so no safety behavior needs restating. The description adds useful output-behavior context beyond the schema by explaining where outcome codes live (report.outcomeAnalysis.outcomes) and how language fields are structured, which helps the agent interpret responses correctly.

Agents need to know what a tool does to the 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 main purpose and output scope are front-loaded, and the second sentence adds clarifying output semantics rather than repeating schema content.

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

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

For a three-parameter read-only tool with an output schema and complete parameter descriptions, this description is complete. It covers the tool's scope, key data fields, outcome-code relationships, and translation-language semantics, so an agent has enough to understand both invocation and returned data.

Complex tools with many parameters or behaviors need more documentation. 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 id, includeFields, and includeReport with their defaults. The description implicitly relates fields[] and report to the include flags, but it adds no additional parameter semantics beyond what the input 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 specific action and resource: "View one form of the current team in full," which clearly distinguishes it from list_forms and get_form_stats. It also specifies what "full" means by naming fields[] and the report configuration, so an agent knows exactly what this tool 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?

The description gives clear context: use this when you need one complete form including its questions and report configuration, not just a form listing or translation. It does not explicitly state when-not against related tools like get_form_translation or list_forms, but the context is strong enough for a retrieval 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 indicate readOnlyHint=true and destructiveHint=false, so the read-only nature is clear. The description adds that it reads from form_sessions telemetry and covers stages, but does not disclose the exact output structure (though output schema exists). It doesn't mention any rate limits or aggregation details, which is acceptable given annotations.

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

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

The description is a single, information-dense paragraph. It front-loads the core purpose, then lists details. It's not overly long for the complexity. The structure could be improved with bullet points, but it remains readable and efficient.

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

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

Given the 2 parameters, rich output schema, and annotations, the description covers the key points: what data is included (stages, channels, UTM combos, drop-offs), the source (form_sessions), and the primary use case. It doesn't explain the output schema, but that's covered by the schema. It might miss specifics like pagination, but with a limited look-back window, that's 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?

Schema description coverage is 100%, so both days and formId are documented in the schema. The description adds the context that 'days' is a look-back window and that the funnel is for the current team, but that's minimal extra. The baseline is 3 since the schema carries the 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 a conversion funnel for a form, enumerates the specific stages (viewed → started → submitted → ...), and mentions per-channel and drop-off variations. It distinguishes itself from 'get_form_stats' and other form tools by specifying the funnel focus and the telemetry source.

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

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

The description explicitly tells when to use it: 'Use this to find where respondents drop and improve conversion.' This is a direct usage guideline. It implicitly differentiates from get_form (form details) and get_form_stats (general stats) by focusing on funnel/drop-off analysis.

Agents often have multiple tools that could apply. Explicit usage 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 declare readOnlyHint=true and destructiveHint=false, so the tool's safety profile is established by structured data. The description adds that it returns delivery settings and embed material, but does not disclose potential behavioral edge cases such as invalid form IDs, required permissions, or rate limits. With annotations carrying the safety burden, this is adequate but not richer than a baseline.

Agents need to know what a tool does to the 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 focused sentences. The first front-loads the full output inventory, the second isolates the one optional parameter that changes the result, and the third gives a concrete use case plus an alternative tool. Every sentence earns its place and no fluff is present.

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

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

There is an output schema, so detailed return values are already documented. The description adds the missing contextual layer: which form scope is used (current team), which intent this tool serves (link/embed/launch sanity-check), and which sibling tool to use for mutation. For a read-only retrieval tool with a full output schema, it is 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%, so formId, utmSource, iframeHeight, and popupButtonText are fully documented in the structured schema. The description only reuses utmSource's meaning ('Pass utmSource to get every link and snippet tagged for one channel') without adding new semantic detail beyond the schema, and it says nothing about iframeHeight or popupButtonText.

Input schemas describe structure but not intent. Descriptions should explain 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 intent—'put a form of the current team in front of an audience'—and enumerates concrete deliverables: public answer link, per-language links, custom domain, embed snippets, and delivery settings. It clearly separates this retrieval tool from siblings such as get_form and update_form_settings.

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

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

It explicitly says when to use the tool: "Use this to answer 'give me the link / the embed code' and to sanity-check a launch" and points to a specific alternative for mutation: "change the switches with update_form_settings." Both selection criteria and an exclusion are stated.

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

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

Annotations already declare 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 the description correctly aligns by describing a non-destructive read operation. It adds behavioral detail beyond annotations by disclosing the error condition (returns error if language version does not exist) and clarifying the returned content (mirrored fields[] and report).

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

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

The description is a single, dense paragraph with no filler. It front-loads the primary action, includes critical context, and routes to the necessary sibling tools. Every sentence adds value; no redundancy.

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

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

For a read-only tool with a rich output schema, the description covers the purpose, usage context, potential error condition, and follow-up actions. It fully equips an agent to call the tool correctly without needing to inspect siblings or infer behavior.

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

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

Schema description coverage is 100% for both parameters (formId and language), so the schema provides full documentation. The description adds context by mentioning 'source form' for formId and using 'which language version to read' for language, which slightly enriches but does not significantly surpass the schema's own descriptions.

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

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

The description clearly states a specific verb ('Read') and resource ('full content of one language version of a form'), and distinguishes itself from siblings like get_form and create_form_translation. It explicitly mentions the fields included, making its scope 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?

It provides explicit when-to-use guidance: 'Use this to fetch the current draft before translating'. It also gives clear when-not-to-use context by explaining error conditions (if language version doesn't exist, create first) and names the sibling tools (update_form_translation, create_form_translation) for the next steps.

Agents often have multiple tools that could apply. Explicit usage 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 mark the tool as read-only and non-destructive, covering the safety profile. The description adds a valuable behavioral detail: email and phone numbers in answers are masked, a privacy constraint the agent should anticipate. It also notes the report is 'frozen,' implying a snapshot, which is useful context beyond the annotations.

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

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

The description is compact, consisting of two sentences with no fluff. The first sentence packs the purpose and included data, while the second adds the masking detail. It is front-loaded and every sentence earns its place.

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

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

An output schema exists, so the response format is already defined externally. The description covers what the tool returns (examinee, answers, UTM, frozen report) and notes the masking behavior, which is sufficient for an agent to call the tool correctly. No additional context like pagination or permissions is needed for this single-read retrieval.

Complex tools with many parameters or behaviors need more documentation. 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 the sole parameter `recordId` with 100% coverage, including its origin from `list_records`. The description reiterates this in text but does not introduce additional meaning or nuances beyond what the schema states. Since the schema carries the semantic load, a baseline 3 is appropriate.

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

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

The description states a clear verb ('View'), a specific resource ('submission record (lead)'), and scopes it to the current team and a single record id. It lists the contents (examinee, answers, UTM, frozen report), and explicitly references `list_records` as the source of the id, distinguishing it from other get/list tools.

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

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

The description provides a clear prerequisite by explaining that the record id comes from `list_records`, guiding the agent on how to obtain the argument. It implies this is the detailed view for one submission record but does not explicitly name alternatives or state when not to use them. The specificity of 'full detail' and the mention of report results give sufficient context to select it for inspection.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: 'Not idempotent: if the call times out it may still have succeeded, so retrying blindly can create a duplicate — check first, then retry only if it is really missing.' This is exactly the kind of behavioral disclosure that goes beyond annotations. It also clarifies that type determines which fields apply and that inapplicable fields are rejected or ignored.

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

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

The description is dense but well-structured: it front-loads the core action and positioning, then the end-case alternative, then the idempotency warning. The schema-level description is long but that's a separate field. The tool description itself is compact and every sentence earns its place. Slight deduction for the schema description being very long, though that's not the tool description's fault.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with 100% schema coverage and an output schema, the description is remarkably complete. It covers positioning, alternatives, non-idempotency, type applicability, and scene rules. The schema's own description field covers the field-applicability matrix in detail. 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 100%, so the baseline is 3. The description adds value by summarizing the field-applicability matrix (which fields go with which type/scene) and by explaining the before/after positioning semantics. However, most parameter-level detail is already in the schema, so the description doesn't need to repeat it. The added value is the cross-cutting applicability guidance.

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

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

The description opens with a specific verb and resource: 'Insert an item at a specific position: a question, a page break (Breaker) or a display block (Statement with `content` / Swiper with `items`).' It clearly distinguishes from siblings like add_question (insert at end) and move_question (reorder existing). The title 'Insert question' is slightly narrower than the description, but the description fully clarifies the broader scope.

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

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

Explicitly states when to use this tool vs alternatives: 'To insert at the end, use add_question.' It also explains how to reference positions via before/after with field codes from get_form, and how to insert at the very front. The non-idempotency warning with retry guidance is a strong usage guideline.

Agents often have multiple tools that could apply. Explicit usage 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=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond that: the API returns earliest first, descriptions fields per item, masks attendee contact info, and indicates the 'pending' status represents an unapproved booking. This adds meaningful context without redundancy or 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 compact and front-loads the primary action and scope. All sentences contribute meaningful context: sorting, returned fields, filters, typical use, and attention-masking. It could drop the slightly redundant 'list' wording, but overall it earns its place without significant bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 full input schema, an output schema, and clear annotations, the description adds what the agent still needs: the meaning of the 'pending' status, the masked/contact-handling behavior, and how to reference a booking by bookingId. Combined with the structured data, the description is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a few semantic hints not always in the schema, such as the meaning of 'pending' as being the approval queue and the ability to filter by status/quiz/respondent/time range. But it doesn't need to compensate for schema gaps, and beyond those hints it functions mostly as a summary.

Input schemas describe structure but not intent. Descriptions should explain 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 tool as listing 1:1 bookings for the current team, specifies the sort order (earliest first), and enumerates what each item contains. It also mentions it filters by status, quiz, respondent, and time range, which distinguishes it from generic list tools and the related booking mutation tools.

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

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

The description gives a concrete typical use case: using status "pending" to view the approval queue waiting on someone. It surfaces privacy behavior (attendee name/email masked) and how to reference a booking by bookingId. It doesn't explicitly state when not to use this tool versus sibling booking tools like review_booking or update_booking_status, but the intended read-only list usage 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?

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 establish the safe read-only behavior, so the description adds value beyond them by specifying reverse chronological order and the omission of question content. It also clearly scopes results to the current team. It does not detail pagination behavior, but the annotated readOnlyHint and the schema's limit parameter reduce the burden.

Agents need to know what a tool does to the 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, each earning its place: the first states the core action and scope, the second conveys ordering, content omission, and the pointer to get_form. There is no redundancy or filler.

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

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

For a simple read-only list operation with zero required parameters, a fully described schema, and an output schema present, the description provides all necessary context: current-team scope, ordering, and a pointer to the detail tool. Nothing essential is missing for an agent to decide when to call and what to expect.

Complex tools with many parameters or behaviors need more documentation. 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 and covers 100% of the parameters, so the description does not need to repeat them. It adds no extra semantic detail about the parameters, but none is needed. The baseline of 3 is appropriate here.

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

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

States a specific action ('List') on a specific resource ('forms of the current team'), and further clarifies scope by excluding question content. The explicit pointer to get_form for details differentiates it from the most related sibling. This leaves no ambiguity about what the tool 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?

The description gives an explicit when-to-use alternative: the tool returns summarized form metadata, and if question content is needed, get_form should be used instead. This directly routes the agent to the correct sibling depending on the need. No further guidance is necessary given the simple read-only nature and optional filters.

Agents often have multiple tools that could apply. Explicit usage 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 cover readOnlyHint and destructiveHint, so the safety profile is known. The description adds behavior beyond annotations: records are sorted newest first, PII such as emails and phone numbers is masked in answers, and records must be referenced by examineeId. This meaningfully enriches the agent's expectation of the tool's behavior.

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

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

The description is three sentences and front-loads the primary purpose, then gives filters and guidance. It is fairly dense but avoids redundancy, with each sentence serving a distinct role. It could be trimmed slightly, but it 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 that the tool has 6 optional parameters, a full output schema, and safe-read annotations, the description covers ordering, item composition, filter dimensions, a reference/masking subtlety, and points to the more detailed single-record tool. There is no substantial gap for an agent 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 description coverage is 100%, so the parameters are already well defined. The description adds extra semantics by grouping since/until as a 'submitted-at range' and warning that email/phone answers return masked, reinforcing reference by examineeId. This goes beyond just restating the schema, though most parameter details remain in the schema.

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

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

The description names a specific verb and resource ('List submission records (leads) of the current team, newest first') and details contained fields (examinee, answers, UTM, report result). It differentiates from siblings by naming get_record for full detail, so an agent can distinguish scope and granularity.

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

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

The description explicitly tells when to use filters, instructs to reference records by examineeId rather than masked email, and directs that single-record full detail should use get_record. This is concrete, actionable when/when-not guidance with an explicit alternative.

Agents often have multiple tools that could apply. Explicit usage 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?

Annotations already indicate non-read-only and destructive behavior, but the description adds meaningfully: the attendee is emailed, the reminder is re-armed, the booking.rescheduled event fires, and retries can repeat side effects. This is beyond what annotations and schema convey and it does not contradict them.

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

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

The description is front-loaded with the core action and each major behavioral note earns its place. It is slightly long and a few parameter constraints are restated from the schema, but the extra detail is valuable 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 tool is destructive, mutating, and externally observable via annotations, the description covers prerequisites, side effects, failure conditions, and retry safety. Since there is an output schema, not explaining the return value is acceptable; the agent has everything needed to call and verify this tool safely.

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

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

The input schema documents both parameters and even includes the availability constraint, with 100% schema coverage. The description mostly repeats that startAt must come from get_booking_availability and adds little new parameter-level meaning beyond 'current team' and 'organiser' context.

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

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

The description clearly states a specific action (move a confirmed booking to a different time), the scope (current team, as organiser), and the main constraints. This distinguishes it from status-changing or reviewing tools like update_booking_status and review_booking.

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

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

It explicitly tells the agent to call get_booking_availability first and choose a startAt from the returned slots. It also gives explicit failure conditions (slot taken, another active booking) and explains not to retry blindly after a timeout, covering both when-to-use and cautious when-not-to-retry behavior.

Agents often have multiple tools that could apply. Explicit usage 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?

Beyond the annotations' destructiveHint, the description discloses the real-world side effects: approving confirms the meeting and emails the attendee the meeting address, while declining sends a 'not approved' note. It also exposes the constraint about already-passed meeting times, which is valuable behavioral information 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 description is compact, front-loaded with the central purpose, and each sentence contributes distinct information: decision semantics, side effects, status constraints, optional parameters, and permissions. There is no filler or redundancy.

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

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

Given the tool's complexity, the description covers prerequisites, permissions, decision outcomes, side effects, and optional parameter behavior. Since an output schema exists, not detailing the response shape is acceptable. Nothing necessary for correct invocation is missing.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description adds context about approval-time link/instructions falling back to team settings, but this is largely mirrored in the schema, so it does not substantially elevate meaning beyond the input 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 leads with a specific verb and object: 'Approve or decline a pending booking request of the current team.' It clearly distinguishes the core review decision from generic status updates, and the outcomes for each decision are explicitly stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 strong usage context: it only applies to pending bookings, past-time meetings can only be declined, and only the team owner/admin/lead owner may review. It does not explicitly name alternative sibling tools like update_booking_status, so it stops short of a full when-to-use-versus-alternatives statement.

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

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

Annotations already indicate destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond that: it discloses that the dimension list is replaced while overallAnalysis is preserved, that dimensions referenced by question dimensionScores or report.formula cannot be removed, and that code stability is maintained for dimensions with the same name. There is no contradiction; the description enhances the annotation. It clearly warns about irreversible replacement and scene-specific 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 dense and long, but every sentence contributes essential context. It is front-loaded with the core action and then layers scene-specific rules and constraints. While it is a single block of text rather than bullet points, it is structurally logical and not redundant. It could be slightly more concise, but the 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 complexity of the tool (scene-specific dimensions, code stability, reference constraints, clearing behavior), the description is comprehensive. It covers prerequisites, limitations (random_knowledge_quiz unsupported), and interaction rules (e.g., formula cannot reference other dimensions). Since an output schema exists, return values are not needed. Nothing essential is missing.

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

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

Although the input schema provides 100% coverage with detailed descriptions, the main description adds meaning beyond the schema by explaining how parameters interact: the stable-code logic (pass code to keep/set, omit to keep by name), the scene-specific requirement for fieldCodes vs formula, and the default behavior for standardScore. This is not a restatement but high-level contextual semantics that an agent needs to construct correct calls.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Set the multi-dimension analysis (form.report.dimensionAnalysis) of a form, replacing the dimension list without touching overallAnalysis'. It clearly distinguishes from sibling tools like update_form_settings by focusing on the dimensionAnalysis attribute, and even names the prerequisite get_form call. This is unambiguous and purpose-specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: it differentiates the knowledge_quiz scene (requires fieldCodes) from the scored_quiz scene (formula optional), and warns that 'Not supported for random_knowledge_quiz forms'. It also states prerequisites ('Call get_form first to read the question and dimension codes') and provides a clear way to clear the analysis ('Pass an empty dimensions array'). This leaves no ambiguity about when to invoke this tool versus alternatives.

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

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

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

Annotations already flag destructiveHint=true; the description adds valuable side-effect context: cancellation triggers attendee email and a booking.cancelled integration event, while completed/no_show are internal-only. It stops slightly short of spelling out whether the underlying booking is deleted or merely marked, so a 4 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?

Four sentences, each earning its place: purpose, conditions, side effects, and alternative. The most decision-relevant constraint is front-loaded and there is no filler or repetition.

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

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

Given the output schema and annotations, the description covers the operation, preconditions, side-effect differences, and sibling routing. There is no gap that would leave an agent guessing about how or when to call this tool.

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

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

With 100% schema coverage, the baseline is 3. The description still adds real meaning beyond the schema by explaining the preconditions tied to each status value ('Only works on ... scheduled; completed / no_show additionally require the meeting to have already started'), which helps an agent choose the correct status. This justifies a 4 rather than a 3.

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

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

The description uses specific verbs and a resource ('Close out a confirmed booking of the current team'), lists the three status transitions, and explicitly differentiates from review_booking. An agent knows exactly what this tool does and what it is not for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 applicability conditions ('Only works on a booking whose status is scheduled; completed / no_show additionally require the meeting to have already started') and a pointer to the correct alternative ('To handle a pending request use review_booking instead'). This is textbook 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?

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?

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the agent knows this mutates and can destroy data. The description adds genuine behavioral value beyond those flags: report and openGraph merge by sub-key (only what is passed is replaced), systemText is replaced wholesale with {} clearing it, outcomes in the outcome_quiz scene are matched by code so existing images survive, and removing an outcome still referenced by question votes is rejected. It also notes landingImage only sets the image and does not toggle the landing page. No contradiction with the annotations.

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

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

The description is a single dense paragraph of roughly 250 words. There is zero fluff and every sentence carries information, but for a tool with 11 parameters and complex merge semantics, a structured format (short intro, then per-behavior bullets) would aid scannability. The key facts are front-loaded in the first sentence, but the remaining run-on sentences compress several distinct behaviors (media handling, merge semantics, outcome matching, systemText replacement, language restriction, sibling routing) into one block, which an agent must parse carefully.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (11 parameters, nested objects, output schema present) and the 100% schema description coverage, the description provides a complete high-level map: it covers merge semantics, media sourcing, the clear-with-empty-string convention, the language restriction, scene immutability, and routes all out-of-scope operations to named siblings. Return values and detailed parameter rules live in the output schema and input schema respectively, so nothing an agent needs to call this 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%, so the schema itself documents every parameter exhaustively (baseline 3). The description adds a compact high-level synthesis: it groups the updatable fields, clarifies the flagImg vs landingImage roles (quiz cover vs landing-page cover, the latter not toggling the page), states both accept a media id from finalize_image_upload, a media URL, or '' to clear, and summarizes the cross-cutting merge vs replace behavior that the schema only documents per-parameter. This is genuine incremental value over the schema, though the schema carries most of the detail.

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

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

The description states a specific verb and resource ('Update a form of the current team') and enumerates exactly which fields are in scope: title / description / isActive / flagImg / landingImage / theme / report / openGraph / language / systemText. It actively distinguishes itself from siblings by routing questions to add_question/update_question and dimensionAnalysis to set_dimension_analysis, so an agent can tell it apart from create_form, update_form_settings, and 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?

The description gives explicit when-to-use and when-not-to-use guidance. It names the sibling tools for adjacent operations ('Questions go through add_question / update_question / delete_question / move_question, dimensionAnalysis alone through set_dimension_analysis') and spells out conditional usage rules: language is changeable only while no language versions exist, and scene is never changeable. It also documents the merge-by-sub-key semantics for report and openGraph, so the agent knows how to construct partial updates. Nothing is left to inference.

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