RooQuiz

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

The description goes well beyond the annotations by disclosing team-only visibility, the 2000-character limit, optional recordId context, and the non-idempotent behavior with timeout risk and duplicate-creation potential. This gives the agent critical operational knowledge that the annotations do not cover.

Agents need to know what a tool does to the 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 deliver the core purpose, visibility scope, constraints, an alternative retrieval path, and idempotency warning without filler. The most important operational warning (non-idempotency) is clearly highlighted at the end and the content is front-loaded.

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

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

For a write operation with three parameters and detailed annotations, this description is complete. It covers what the note is, who can see it, how long it can be, how to optionally link a record, where to read existing notes, and how to handle retries safely. No essential guidance 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 schema already documents all three parameters fully, so the baseline is 3. The description adds contextual meaning for recordId ('as context') and explicitly restates the character limit, adding a bit of purpose beyond the schema definitions. Still, the schema does the heavy lifting, so this is not a 5.

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

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

The description names the exact action ('Write an internal follow-up note') and the specific resource ('a lead of the current team'), and adds the meaningful scope of being visible only to team members, never to the respondent. This distinguishes the tool clearly from other lead-related or comment-related tools in the sibling list.

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

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

The description clearly communicates the intended audience and context, and points the agent to retrieve existing notes using get_lead(includeComments: true). It lacks an explicit 'use this tool when... not when...' statement, but the internal-vs-respondent distinction and the retry warning effectively convey appropriate and inappropriate use.

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

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

The description explicitly warns that the call is not idempotent: if it times out it may still have succeeded, so retrying blindly can create a duplicate and the agent should check first. It also discloses that fields irrelevant to a given type are ignored or rejected, and that some types are scene-restricted. These behaviors go well beyond the bare readOnlyHint/destructiveHint 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 front-loaded with the core purpose and ends with the critical non-idempotency warning, which is good. However, it is very long and duplicates much of the detailed per-parameter guidance already present in the input schema, so not every sentence earns its place. A tighter scene/type summary would be more concise without losing 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?

Given the tool's complexity — 14 question types, 4 quiz scenes, 28 parameters, nested objects, and scene-specific scoring rules — the description is remarkably complete. It covers type availability, field applicability, ignored/rejected behavior, and the retry-after-timeout risk. The output schema exists, so not 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?

Schema description coverage is 100%, and each parameter already has a detailed explanation of meaning, applicability, and rejection rules. The tool description adds helpful summarization and type-selection guidance, but it largely restates what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Append an item to the end of a form." This clearly distinguishes it from sibling tools like insert_question, move_question, update_question, and delete_question. It also enumerates the supported question types, so an agent can immediately understand the tool's 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 clear context for when to use the tool: it is for appending an item to the end of a form, and it explains type-specific usage preferences such as preferring DropDown over SingleCheck/MultiCheck past 20 choices. It does not explicitly name alternatives like insert_question for non-end placement or update_question for edits, but the append-to-end semantics make the primary use case 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?

The description explains important behavioral facets beyond annotations: each change is recorded on the lead timeline, the assignee gets one aggregated notification, and omitting/null clears the assignee. This informs the agent of mutation effects without needing to infer 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?

Each sentence earns its place: purpose, batching instruction, assignee eligibility, unassign behavior, and side effects. It is compact yet complete and well-organized.

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

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

For a two-parameter tool with an output schema, the description covers all essential call semantics: what to pass, how to unassign, member constraints, and result behavior. No additional context or inference is necessary for correct invocation.

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

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

The schema already covers 100% of parameters with clear descriptions. The description adds meaningful context above that: leads must belong to the current team, the assignee must be an active non-viewer member, and the batch limit is emphasized.

Input schemas describe structure but not intent. Descriptions should explain 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 operation ('Assign one or more leads of the current team to a member, or clear the assignee'), making the tool's purpose unmistakable. It is distinct from siblings like set_lead_tags or update_lead.

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

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

Gives explicit guidance: pass every lead id in a single call up to 50, do not loop, use 'me' for yourself, and omit/null to unassign. It also states the assignee eligibility requirement clearly.

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 openWorldHint=true and destructiveHint=false, and the description adds substantive behavioral context on top: not idempotent (timeout may still succeed, retry can duplicate), creates primary language only, returns question codes in structuredContent, and requires outcomes at create time. This goes well beyond what annotations alone communicate.

Agents need to know what a tool does to the 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 organized: it front-loads the core verb, then use-case specifics, then retry behavior. Every sentence earns its place and none merely repeats schema text, though it is long enough that a reader must parse carefully. The structure is tight and information-dense, which justifies a 4.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a rich output schema and a 100% documented input schema, so the description does not need to restate return values. It covers all the gaps an agent would otherwise hit: when outcomes are required, how to handle codes/formulas across calls, language handling, and the timeout/duplicate caveat. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds high-value meaning beyond the schema: it explains the create-time vs follow-up ordering, the requirement that outcome_quiz needs report.outcomes at creation, the interplay between codes and formulas in one call, and the non-idempotency retry rule. It also orients the agent to the returned fields for later update steps.

Input schemas describe structure but not intent. Descriptions should explain 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 distinguishes itself from siblings by clarifying it creates the primary language only (add other languages via create_form_translation). The one-call philosophy is explicit, and it is clearly differentiated from create_form_from_template as a create-from-scratch tool.

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 when-to-use guidance: it tells the agent to pass questions and report together in one call instead of following up per question, explains which scene needs outcomes at create time, and routes follow-on work (formula, dimensionAnalysis) to update_form / set_dimension_analysis. It also explicitly warns about a non-idempotent timeout behavior and how to handle it.

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

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

The description meaningfully extends the annotations (readOnlyHint=false, destructive=false) by detailing cloning scope, title override semantics, and post-creation mutability. Crucially, it discloses non-idempotency and the retry-after-timeout risk with actionable guidance to check before retrying. This is exactly the behavioral context agents need beyond 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?

Four sentences, each earning its place: purpose plus template ID source, cloning scope and title override, post-creation workflow, and idempotency warning. Front-loaded with the primary action, then progressively operational details. No filler or repetition yields a tight, high-signal definition.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers everything needed to invoke it correctly: input format, where to get the ID, what gets cloned, why to prefer it, and what to do on timeout. The non-idempotency warning is especially valuable for reliable agent execution.

Complex tools with many parameters or behaviors need more documentation. 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 pointing to list_templates as the source for valid template IDs and by clarifying that title overrides the template title, paralleling the schema. It doesn't fully expand parameter meanings, but the added context is helpful and non-redundant.

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

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

The description opens with a precise verb-resource pair: 'Create a new form in the current team from a public template.' It also names the sibling tool it is not — create_form — and emphasizes this is the template-based pathway. Clear, unambiguous, and distinct from siblings.

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 guides when to choose this tool: '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 references list_templates for finding IDs and update_form/update_question for subsequent changes. It does not exhaustively state when not to use it (e.g., no template exists), but the context is clear enough.

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

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

The description thoroughly discloses behavior beyond annotations: it clones source text as the initial draft, returns the draft for immediate editing, requires keeping codes identical, and enforces one translation per language and language differing from primary. This gives the agent a clear mental model of what will happen.

Agents need to know what a tool does to the 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 compact, front-loaded description that packs essential info into three sentences: the action, the return and workflow, and the constraints. No filler or redundant restating of the schema.

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

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

The description fully covers what an agent needs to invoke this tool correctly: the purpose, the workflow, constraints, and where to verify uniqueness. The output schema covers return-value details, so the description completes the behavioral picture.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for 'language' (must differ from primary, one per language) and clarifies that 'formId' is the source form. It also explains that clones source text, tying parameters to the behavior.

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

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

States a specific verb and resource: 'Add a language version (translation) to a form.' It clearly differentiates from related siblings like update_form_translation (for saving edits) and list_form_translations (for checking existing translations).

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

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

Gives clear usage context: use this to create a translation, then save with update_form_translation, and check list_form_translations for uniqueness. It could be more explicit about when not to use it or which alternative covers different cases, but the workflow is well communicated.

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

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

Annotations only provide destructiveHint=true, and the description substantially expands on that: soft-delete semantics, 5-day retention then auto-purge, submission records preserved until permanent purge, and the restore path. This is exactly the behavioral context an agent needs beyond a bare destructive flag, and it does not contradict the annotations (destructiveHint=true aligns with moving to trash).

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

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

Three sentences with no filler: core action and scope, recovery window with the restore path, then permissions and submission handling. The most decision-relevant fact (this is a soft delete, not a permanent deletion) is front-loaded in the first sentence.

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

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

For a single-parameter mutation tool with a present output schema and a destructiveHint annotation, the description covers action, scope, retention, recovery, permissions, and side effects on submissions. Remaining gaps such as idempotent re-deletion or permission-denied error codes are minor edge cases, and the output schema covers return-value expectations.

Complex tools with many parameters or behaviors need more documentation. 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 is already documented as 'The form UUID to move to trash.' The description adds the 'current team' scoping, which usefully constrains which formId is valid, but it provides no additional format or validation guidance beyond the schema. Baseline 3 is appropriate when the schema already 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 opens with a specific verb and resource: 'Move a form into the trash (soft delete) in the current team,' which immediately clarifies not only what the tool does but its non-permanent nature. It also differentiates from siblings by naming restore_form as the inverse and by making the resource (form) distinct from delete_form_translation and delete_question. An agent can disambiguate without opening 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?

It names restore_form as the explicit recovery alternative, tells the agent the hidden-from-list_forms consequence, and states the permission precondition (form owner or team owner/admin). It stops short of an explicit when-not-to-use directive, but since no hard-delete sibling exists, the guidance is clear and actionable for the tool family.

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

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

The annotations only indicate destructiveHint=true, so the description adds valuable behavioral detail: submission records are anchored to the source form and are NOT deleted, historical reports fall back to source text, and the primary language cannot be removed through this tool. This is exactly the kind of side-effect disclosure that helps an agent predict real-world impact.

Agents need to know what a tool does to the 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 make the core action, the critical side effects, and the primary-language restriction very clear. Nothing is redundant, and the most important behavioral caveat about submissions is placed early.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 small tool with two well-documented parameters and destructive semantics. The description fully covers what gets deleted, what does not get deleted, what happens to historical reports, and which language is off-limits. No material information needed to invoke the tool safely 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 fully documents both parameters and the language enum, so the baseline is 3. The description adds meaningful parameter-level context by confirming that the language parameter refers to a translation version and that the primary language is not a valid candidate for this deletion.

Input schemas describe structure but not intent. Descriptions should explain 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: delete one language version (translation) of a form. It also distinguishes this from deleting the whole form by noting the primary language cannot be deleted this way, which helps an agent differentiate it from delete_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 gives a clear usage context: deleting a translation while preserving submission records, and it explicitly excludes the primary language. It does not explicitly name delete_form as the alternative for removing the primary language, but the phrase 'it lives on the form itself' makes that route reasonably clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description correctly doesn't repeat the mutation warning. It adds genuine value beyond the annotations with the 'deleting the last one is allowed (a form can be an empty shell)' edge case, which prevents an agent from assuming a minimum-item guard exists.

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

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

Two sentences, roughly 30 words, fully front-loaded: action and scope in the first sentence, the one critical edge case in the second. Every sentence earns its place and nothing repeats schema or annotation 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?

Complete for a low-complexity tool: both required parameters are fully described in the schema, destructiveHint covers the safety profile, and an output schema covers return values. The only behaviors an agent needs to call it correctly — what can be deleted, by which identifier, and the last-item allowance — are all present.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds one meaningful clarification: 'by code' confirms the code parameter is the deletion identifier, and it corrects the schema's narrow 'question' wording by revealing that code may reference breakers and display blocks as well as questions.

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

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

States a specific verb (Delete) and resource ('a single item from a form'), then disambiguates the resource by enumerating the three deletable item types (question, Breaker, Statement/Swiper). This clearly distinguishes it from sibling delete_form (whole form) and from the question-management siblings (add_question, insert_question, update_question, move_question).

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

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

The usage scope is clear: single-item deletion within a form, with the admissible item types enumerated so an agent knows the tool is not limited to questions. It implicitly contrasts with delete_form (whole-form deletion) via the 'single item from a form' phrasing, though it never names the alternative or states an explicit when-not condition.

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 materially extends the annotations by revealing non-idempotence: if the call times out it may still have succeeded and blind retries can create duplicates. It also discloses ownership transfer, fresh share links, and that records/integrations/ban state are not copied. This is exactly the kind of behavioral nuance an agent needs beyond the readOnly/destructive hints.

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

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

The description is front-loaded with the core action, then quickly states inclusions, exclusions, and a use case. The non-idempotence warning is placed last but earns its place as a critical caveat. No filler or redundant restatement of the tool name/schema.

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

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

For a two-parameter tool with an output schema and annotations already present, the description covers the essential behavior: what is created, what is excluded, ownership, and the non-idempotence risk. It also gives a realistic use case. Nothing relevant to invoking it correctly is absent.

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

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

Schema coverage is 100%: sourceFormId and newTitle are fully described in the input schema, including the default title behavior. The description does not add parameter-level derivation information itself. This matches the baseline for a high-coverage schema.

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

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

The description states a precise verb and resource — 'Duplicate a form in the current team' — then enumerates exactly what is cloned (structure, scoring, report, visual settings, translations) and what is not (submissions, sharing, integrations, ban state). This clearly distinguishes the tool from sibling create/restore/update operations 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 provides clear context: use it to clone an existing proven quiz and then tweak the copy. It also defines scope by stating what is not copied, which implicitly tells an agent when this tool would not suffice (e.g., if submissions or sharing must be preserved). It stops short of explicitly naming alternatives or when to prefer create_form_from_template, so it earns a 4 rather than a 5.

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

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

The description explains that the tool verifies storage, records the object, and returns a media id plus public URL. This goes beyond the annotations, which only indicate readOnly=false/destructive=false. It does not describe failure handling or idempotency, but the key behavioral steps are 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 sentences, all front-loaded: the very first clause identifies the step and prerequisite. Every sentence adds a distinct, necessary piece of information: when to call, what it does, and what to do with the result. 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 that an output schema exists, the description need not list return fields. It covers the workflow position, prerequisite, effect, and downstream integration. It could optionally mention failure behavior or idempotency, but for invoking this step correctly, the description 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%, and each parameter is already described (key, filename, mimeType). The description adds the workflow context that these values must match the prepare step, but it largely repeats what the schema descriptions already say. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Step 2 of 2 for adding an image' and states it 'verifies the uploaded object, records it in the team media library and returns a media id + public URL.' It clearly distinguishes itself from prepare_image_upload by explicitly naming it as the preceding step and from update_form as a later consumer of its media id.

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 the exact timing ('call this AFTER you have PUT the file to the uploadUrl returned by prepare_image_upload'), the alternative usage ('to use the image as a quiz cover or landing-page cover, call update_form with flagImg or landingImage'), and the sequencing. No ambiguity remains about when to invoke this tool versus its siblings.

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

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

Annotations already mark this as safe and read-only, and the description adds substantial behavioral context beyond them: the team is the default for all write tools, and examineeSignupDisabled means new respondents cannot sign in at login-gated quizzes. This greatly helps the agent interpret results without contradicting annotations.

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

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

The description is two sentences, front-loads the core purpose, then explains an important diagnostic flag. Every clause earns its place; no filler or repeated structural metadata.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 handles return structure and there are no params, this description provides the contextual information an agent needs to interpret and use the result, including the critical examineeSignupDisabled nuance and its user-facing consequences.

Complex tools with many parameters or behaviors need more documentation. 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 schema description coverage is 100%, so there is nothing for the description to clarify. Baseline 4 is appropriate since there is no parameter burden.

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

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

The description states a specific operation with verb and resource: "Return the team (tenant) this token is currently operating against." It also clarifies the team's role as write default, making it instantly distinguishable from siblings like list_my_tenants and 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 clear context for when to call it: to identify the active tenant before write operations and specifically to check examineeSignupDisabled before diagnosing submission failures. It does not explicitly name alternatives, but practical use cases are clear and no exclusions are needed.

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 is already true, the description adds useful behavioral context that annotations do not provide: the enabled:false state for disabled plans, exclusion of a booking's own slot during rescheduling, and server-side clamping of over-long date ranges. 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 sentences, each carrying distinct value: core operation, edge-case return, rescheduling workflow, and range limit behavior. The most important use-case instruction is clearly placed, and there is no filler or repetition of schema details.

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

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

For a read-only tool with a rich schema and output schema available, the description covers the query behavior, conditional logic, critical rescheduling prerequisite, and server-side adjustments. It gives an agent everything needed to call it correctly in the main workflow.

Complex tools with many parameters or behaviors need more documentation. 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 three parameters well, including ISO datetime semantics and exclusivity of toDate. The description adds extra meaning by explaining bookingId's exclusion behavior and the server-side range clamp, which helps an agent understand edge cases without opening additional documentation.

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

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

The description states a specific verb and resource: 'Read the current team's bookable time slots in a date range.' It also explains the calculation rule ('weekly booking rules minus what is already taken'), which makes the tool's purpose concrete and distinguishable from siblings like list_bookings or reschedule_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?

The description explicitly instructs agents to 'always call this before reschedule_booking' and gives the reason: a start time outside the available slots is rejected. It also provides conditional guidance for when to pass bookingId and when to omit it, which is actionable and clear.

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

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

Annotations already cover readOnlyHint and destructiveHint, and the description adds useful behavioral details: scoping to the current team and explicitly stating that sensitive auth fields are never returned.

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

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

The description is two concise, front-loaded sentences with no filler. It covers the key facts in order: action, scope, identifier, included data, and an important security guarantee.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 one well-documented parameter, read-only annotations, and an output schema being present, the description is complete enough for an agent to correctly select and call the tool. Team scope, ID source, included data, and excluded fields are all stated.

Complex tools with many parameters or behaviors need more documentation. 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 examineeId as the business ID shown in list_examinees. The description repeats the same example and adds little beyond what the parameter schema already provides.

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

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

The description states a specific verb ('View the full detail of one examinee') and a specific resource, clearly distinguishing a full single-record lookup from list_examinees. It also mentions the key identifier and that customData is included.

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

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

It clearly sets the context: use this on an examinee in the current team, and find the examineeId from list_examinees. It does not explicitly name alternatives or exclusions, but the intended read-only retrieval flow is clear.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description is fully consistent with a pure read operation. The description adds value by disclosing where outcome codes live (report.outcomeAnalysis.outcomes) and that language is the primary language with others listed in translationLanguages. It does not mention rate limits or pagination, but with a read-only safety profile these are minor rather than critical gaps.

Agents need to know what a tool does to the 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 front-loads the main purpose in the first sentence and keeps the follow-up snippet compact. The dense references to fields[], report configuration, outcome codes, and language are informative; no filler or repeated schema information. It is slightly more technical than it needs to be, but each clause earns its place.

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

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

The output schema exists, annotations cover the safety profile, and all parameters are documented in the input schema. The description closes the remaining gap — understanding how the response is organized — by pointing exactly where outcome codes and language variants live. Nothing an agent needs to invoke this tool correctly is absent.

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

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

Schema description coverage is 100%, so the baseline is 3 even without extra parameter context. The description's notes about outcomeAnalysis and translationLanguages describe the response shape rather than the input parameters, so it doesn't materially enrich the meanings of the already clearly documented id/includeFields/includeReport parameters.

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

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

The description opens with a specific verb and resource: 'View one form of the current team in full', then states precisely what is returned (fields[] and the report configuration). It naturally differentiates from siblings like get_form_stats, get_form_funnel, get_form_translation, and list_forms, since the scope is a single complete form definition.

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

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

The usage context is implied — a caller needing the full form detail, including question fields and report config, would reach for this tool. However, the description never names any alternatives or excludes when the agent should prefer a sibling like get_form_stats, get_form_translation, or list_forms. The selection rule has to be inferred from sibling names and the 'in full' wording.

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

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

Annotations already declare readOnly and non-destructive behavior, so the description doesn't need to echo those. It additionally discloses what data is used ('form_sessions telemetry'), what breakdowns are computed, and the drop-off analysis, going beyond the annotations and leaving no surprising behavioral traits.

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

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

The description is one dense sentence with no filler. It front-loads the tool's core purpose, then adds only high-value specifics: telemetry source, overall stages, channel breakdown, UTM combos, and drop-off points. Every phrase earns its place.

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

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

With an output schema, a complete input schema, and annotations covering read-only safety, the description provides the remaining operational context: the exact funnel event stages, per-channel and UTM dimensions, and the prescribed use case. An agent has everything needed to decide and 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?

Since the schema already fully documents the parameters (formId and days with defaults and limits), the baseline is high. The description adds meaningful scope by saying 'for a form in the current team' and 'over last N days', tying the parameters to the intended semantic context without repeating schema fields.

Input schemas describe structure but not intent. Descriptions should explain 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 the conversion funnel for a form', names the telemetry source, and pinpoints the scope ('current team', 'last N days'). It also lists the exact analytics dimensions (channels, UTM, stages, drop-off points), making it obviously distinct from siblings like get_form or get_form_stats.

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

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

The explicit closing guidance 'Use this to find where respondents drop and improve conversion' gives a clear when-to-use context. Exclusions or direct alternative names are not stated, but the description is enough for an agent to select it for funnel diagnostics.

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 provide readOnlyHint=true and destructiveHint=false; the description adds useful behavioral context by explaining what the tool reveals, including whether the form will accept responses. It does not contradict any 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 information-dense without fluff: it packs the return contents, the utmSource tagging effect, and the sibling tool reference into two sentences. Every clause earns its place.

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

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

For a read-only getter with rich output, strong annotations, and complete schema descriptions, this description gives the agent everything it needs to decide when to call it and what it will get back. No meaningful gap remains.

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

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

The schema covers all 4 parameters at 100% with detailed descriptions, so the baseline is 3. The description adds some context for utmSource (tagging links/snippets for one channel) but does not meaningfully go beyond the schema's existing 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 identifies the tool's purpose with specific deliverables: public answer link, custom domain status, embed snippets, and delivery settings. It explicitly names the sibling tool update_form_settings to distinguish the read/get nature of this operation.

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

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

Provides explicit use cases: answering 'give me the link / the embed code' and sanity-checking a launch. It also directly states when to switch to update_form_settings, giving the agent clear routing guidance among siblings.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that: the tool is scoped to the current team, respects a time window, and returns an aggregation of metrics rather than raw records. This goes beyond what the annotations alone convey.

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

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

The description is front-loaded with the main purpose, followed by an organized enumerated list of statistics, ending with a useful intent statement. The list is somewhat long, but every element provides meaningful context about the return value; no filler or redundant information is present.

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

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

Given that the tool has an output schema and a rich description listing the exact statistics returned, the description is nearly complete. It covers scope, time span, and the metrics available, though it could go slightly further in differentiating from closely related tools like get_form_funnel or specifying the current-team prerequisite more explicitly.

Complex tools with many parameters or behaviors need more documentation. 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 formId and days with descriptions, and schema description coverage is 100%. The description adds 'over the last N days' and the notion of 'current team', but it does not provide additional parameter-level meaning beyond what the schema already gives. 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 opens with a specific verb and resource: 'Read submission statistics for a form in the current team over the last N days.' It then enumerates the exact categories of statistics returned, making the tool's function unmistakable and clearly distinct from siblings like get_form or list_examinees.

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 closing sentence gives a clear use case: 'Use this to gauge how a quiz is performing and to suggest improvements.' This provides context on when the tool is appropriate, though it does not explicitly name exclude alternatives or state 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 readOnlyHint=true and destructiveHint=false, signaling a safe read. The description adds meaningful context beyond that: it discloses the error condition ('Returns an error if that language version does not exist yet') and the precondition. It also reveals what is disclosed via the fields listing. It does not describe response format, but an output schema exists, so the need is minimal.

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

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

Three short sentences cover purpose, workflow usage, and error condition with zero filler. The purpose is front-loaded; the workflow guidance and precondition follow logically. No sentence is wasted.

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

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

Given the tool's simplicity (2 params, 100% schema coverage, output schema present), the description covers everything an agent needs: what it reads, how it should be used in the translate workflow, and what happens when the language version is missing. Nothing essential is missing.

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

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

Schema coverage is 100%, with both formId and language fully documented. The description adds context by explaining that 'language' selects a 'language version (translation)' and that codes must remain identical to the source form, but it does not go deep on what formId's value means beyond the source form's UUID. Baseline 3 is appropriate on schema does 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 uses a specific verb-resource pair: 'Read the full content of one language version (translation) of a form,' and names the exact scope ('mirrored fields[] and report'). This cleanly separates it from the base get_form and from the other translation tools by specifying that it targets a language-specific variant.

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 embeds the tool in a workflow: 'Use the content to populate an onboarding request the current draft before translating ... then save with update_form_translation.' It also tells the agent when NOT to call it - if the translation doesn't exist, create it first. This is ideal guidance without any additional effort.

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 read-only and non-destructive. The description goes beyond annotations by disclosing exactly what the read returns, what each optional include expands, and that identifier lookup is scoped to the current team. The masked-email warning is a helpful behavioral constraint not present in the schema alone.

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

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

Two sentences with no redundancy: the main action and return fields are front-loaded, optional behavior is listed compactly, and the key identifier caution is a short final clause. Every sentence earns its place.

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

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

With an output schema present and annotations covering the safety profile, the description fills the remaining gaps: what data is included, what optional includes add, and how to correctly reference lead and respondent. 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 schema already documents each parameter. The description still adds value by specifying that leadId is the leadId returned by list_leads, reinforcing which identifier to pass, and warning against using masked emails. Optional flags are semantically clear in both schema and description.

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

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

The description states a specific verb and resource ('View one lead'), names the lead identifier, and enumerates exactly what data is returned (status, assignee, tags, respondent block, next upcoming booking). This is clearly distinct from sibling tools like list_leads or get_examinee because the scope is explicitly 'one lead of the current team'.

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

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

The description clearly indicates when to use this tool: to view a single lead in the current team. It also explains how to reference identifiers ('by its leadId ... never by a masked email') and when to enable optional inclusions such as submission history, internal comments, and change timeline. It does not explicitly name sibling alternatives like list_leads for broad queries, but the use 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 indicate this is a read-only, non-destructive operation. The description adds meaningful behavioral transparency beyond the annotations: it discloses privacy masking of email addresses and phone numbers in submitted answers and explains that the answer are the submitter's answers except for that masking. This is valuable context for an agent deciding whether results are raw or scrubbed.

Agents need to know what a tool does to the 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 structured with the primary action and key facts front-loaded: the specific resource, the source of the id, and the detailed content of the returned record. The second sentence adds important masking behavior. It is fairly long, but the detail is pertinent and each sentence earns its place.

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

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

Given the tool has a rich output schema, the description does not need to enumerate the return fields. It appropriately covers how to locate the record (`id` from list_records), the team scope, the inclusion of UTM metadata, the frozen report, and the masking behavior. Nothing critical seems missing for an agent to invoke 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 input schema already fully documents `recordId` as 'The record id (the `id` returned by list_records)'. The description essentially repeats the same information without adding new parameter nuances such as formats, constraints, or valid values. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly identifies a specific action ('View') and resource ('one submission record / lead'), and details exactly what is contained in the returned detail. It also ties the resource to the `id` field from list_records. It does not explicitly contrast itself with siblings like get_lead or get_examinee, so it lacks complete sibling differentiation.

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

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

The description gives clear context on when to use the tool: after obtaining a record id from list_records, for viewing the full detail of a submission in the current team. It does not explicitly state when not to use it or which alternatives to prefer, but the intended entry point of use is clear.

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

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

The description discloses a critical behavioral trait beyond the all-false annotations: '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 non-idempotency warning with a check-first-retry recipe is exactly the safety context an agent needs for a mutation tool, and it appears nowhere in the annotations or 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?

Four sentences, each with a distinct job: what can be inserted, how positioning works, edge cases (front/end), and the retry-safety warning. The core purpose is front-loaded and there is zero filler — impressive given the enormous schema it accompanies.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a rich schema-level FIELD APPLICABILITY block and a present output schema, the prose covers the agent-facing gaps: sibling routing, reference-code sourcing, edge-positioning behavior, and idempotency. Nothing an agent needs to decide between insert_question and add_question, or to position an item correctly, is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description pushes above it by explaining where the before/after values come from ('reference an existing field code (from get_form's field.code)') and how to encode the front-insection case. The schema's own entries for before/after are thin ('Insert after this code; choose either after or before'), so this resolves a real ambiguity, though the remaining 28 parameters are left to the schema, which fully documents them.

Input schemas describe structure but not intent. Descriptions should explain 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`)' — naming exactly what the tool creates and where. It also differentiates from the closest sibling by routing end-of-form inserts to add_question.

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?

States the when explicitly: insert at a position referenced via after/before against an existing field code. It names the alternative (add_question) for appending at the end, explains the front-insertion edge case ('before references the first field's code'), and tells the agent where to source reference codes (get_form's field.code).

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 that an invitation email is sent, that a join link is returned, and that non-admin roles are rejected. It also lists concrete failure conditions such as existing membership, pending invites, and hitting the member limit. This matches the readOnlyHint=false and openWorldHint=true annotations without contradiction.

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

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

The description is dense but every clause carries useful information: core action, return value, authorization, role constraints, failure modes, and tenant targeting. It is front-loaded with the main behavior and does not include filler or redundant material beyond acceptable reinforcement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 available, the return value structure is already specified, and the description still covers the join-link return, authorization requirements, role constraints, failure conditions, and the active-tenant dependency. An agent has enough context to invoke the tool correctly and handle expected errors.

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

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

Schema description coverage is 100%, and the schema already documents role defaults and meanings. The tool description adds the 'cannot invite as owner' constraint and some email-related failure conditions, but it largely restates what the input schema already provides, so it adds only marginal semantic value.

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

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

The description opens with a specific verb-resource pair: 'Invite someone to the active team (tenant) by email.' It also clarifies the outcome by stating that an invitation email is sent and the join link is returned. This clearly separates it from team-scoping siblings like list_my_tenants and switch_active_tenant by noting it operates on the 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 explicitly states who may invoke the tool: only the team owner or an admin, with rejection for other roles. It also tells the agent to use list_my_tenants or switch_active_tenant first if a different team is intended, which is direct usage guidance and alternative routing.

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

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

Beyond the readOnlyHint annotation, the description discloses important runtime behavior: bookings are scoped to the current team, results are returned earliest-first, attendee name/email are masked, and pending status depends on requireApproval. The mention of masking and the approval model is genuinely valuable and not visible from the schema.

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

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

The description is compact and well organized: what is listed, what fields come back, what filters exist, a typical use, and a key PII mask. Every sentence earns its place, with no filler or restating of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 listing tool with nine optional parameters, the description covers the payload shape, filtering semantics, sorting, a pragmatic example, and the data masking behavior. Combining this with a complete schema and output schema leaves almost no open questions for invoking the tool correctly.

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

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

Schema coverage is 100%, so the baseline is solid, but the description adds real semantic value: it maps formId to quiz, recordId to submission record, and clarifies that examineeId is the internal id from get_lead's respondent.id, not the business code. It also explains what status 'pending' means in 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 states a specific verb ('List') plus a clearly bounded resource: '1:1 bookings of the current team.' It gives the booking origin, the sort order, and what each item contains, which unambiguously distinguishes it from siblings like reschedule_booking, review_booking, or update_booking_status.

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 a concrete use case ('status "pending" lists the approval queue') and explains when requester approval applies. It does not explicitly contrast against alternative booking-related tools, but the context is clear enough for an agent to know this is the read-side listing tool.

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

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

The description adds meaningful behavior beyond the readOnlyHint annotation: sensitive auth fields are never returned, the business ID is returned unmasked, results are scoped to the current team, and results are newest first. This helps the agent understand privacy guarantees and naming semantics without assuming from the schema.

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

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

The description is three tightly written sentences with no filler. It front-loads the core action and scope, then states the privacy guarantee, and closes with actionable routing to sibling tools.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 schema, full schema parameter coverage, an output schema, and annotations declaring read-only non-destructive behavior, the description still adds crucial context about current-team scope, ordering, sensitive-field filtering, and the returned ID's role in get/update operations. Nothing essential 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?

Input schema coverage is 100% and each parameter (limit, search, status) already has a clear description. The tool description adds no extra parameter semantics, so the baseline score of 3 applies.

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

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

The description names a specific verb and resource ('List the examinees'), specifies the scope ('of the current team'), and gives the ordering ('newest first'). It further clarifies the domain by noting examinees are also called respondents, and distinguishes itself from get_examinee by stating the list returns an unmasked examineeId used by that tool.

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 directs the agent: 'Use get_examinee for one examinee's full detail including customData.' It also explains that the returned examineeId is what get_examinee / update_examinee take, making the retrieval-and-update workflow clear. This is strong routing guidance relative to siblings.

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

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

Annotations already mark it as read-only and non-destructive. The description adds meaningful behavioral context: ordering by creation date, exclusion of question content, and team scoping. These details are valuable beyond the annotation flags.

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

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

Two concise sentences, no filler, with the core behavior front-loaded and the pointer to get_form added without awkwardness. Every phrase earns its place.

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

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

For a simple read-only list tool, the description plus full schema plus output schema provides everything an agent needs: scope, ordering, content exclusions, filtering options, and next-step guidance for details. 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?

Input schema covers 100% of parameters with descriptions for limit, scene, and titleContains, so the schema already carries the parameter documentation. The description does not add parameter-level details, which is acceptable given the high schema coverage.

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

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

States a concrete verb and resource ('List the forms of the current team') and adds essential output behavior: reverse chronological order and no question content. This clearly differentiates it from get_form, which is explicitly referenced for details.

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: this is for browsing forms of the current team, and get_form is the alternative when detailed question content is needed. It does not enumerate every sibling distinction, but the key alternative route is explicit.

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

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

Annotations already mark this as read-only and non-destructive. The description adds useful behavioral context by disclosing exactly what is returned (language, isActive flag, public share link, timestamps) and what is excluded (primary language). This 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 tightly written sentences with no filler. The main operation is stated first, followed by return details and a useful scope clarification. 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 simple read-only list tool with a single fully documented parameter and an output schema, the description is complete. It tells the agent what the tool does, what it returns, and what it deliberately omits.

Complex tools with many parameters or behaviors need more documentation. 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 provides high coverage with a well-described required parameter formId. The description adds no additional parameter guidance, which is acceptable given the schema covers the only 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, using a specific verb and resource. It also differentiates itself from get_form by explicitly noting the primary language is not included.

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

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

The description provides clear context by indicating that primary language is handled via get_form.language and is excluded here. It does not explicitly mention alternatives like get_form_translation for single translations, but the scope is clearly communicated.

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, which is a strong safety signal. The description adds behavioral context beyond annotations: the returning structure of leads, 'Newest activity first by default', and scope across all forms. It doesn't discuss pagination edge behaviors, but the schema covers those details and there is 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 compact and front-loaded: the first sentence explains the resource and scoping, the second covers default behavior, the third gives the filter dimensions, and the last gives two critical usage caveats. No redundant phrases or repeated schema text; every sentence adds information.

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

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

The annotations, full parameter schema, and output schema together already provide much of the low-level detail. The description covers the rest: core scope, default sort, filter categories, and the essential 'never guess' warning. There is no significant missing context an agent would need to invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description adds genuine value on top: the reminder that status and tag codes are team-defined and must come from list_lead_settings, and the warning to reference leads by explicit identifiers rather than masked emails. These are crucial practical semantics not completely derivable from the parameter descriptions alone.

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

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

Clearly states a specific verb and resource: 'List the leads (CRM records) of the current team', with explicit scoping 'one lead per respondent across all forms'. It carries meaningful detail about fields like follow-up status, assignee, tags, submission count, and next upcoming booking, which distinguishes it from sibling list tools such as list_examinees and list_records.

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

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

The description gives clear context for when to use this tool: listing leads with filters and default ordering. It also provides important prerequisite guidance: status and tag codes are team-defined and must be fetched from list_lead_settings first, with the instruction to never guess. It does not explicitly exclude alternatives like get_lead for single-lead retrieval, but the use case is otherwise well scoped.

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 disclose readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations by specifying what configuration is returned and why it matters for later writes, including the rejection of unknown values. It does not go into authentication or rate limits, but they are not needed here.

Agents need to know what a tool does to the 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 fluff. The core purpose is front-loaded, and the critical 'call before writes' warning is placed prominently in the second sentence. Every phrase earns its place.

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

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

With zero input parameters, an output schema present, and readOnly/not destructive annotations, this description fully covers what an agent needs: what is read, why it is read, and how it affects planned write calls. Nothing critical 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 has zero parameters and the description correctly does not attempt to invent parameter semantics. The description focuses on what is returned rather than inputs, which is appropriate for a no-parameter read tool.

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

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

The description clearly identifies the operation as reading the current team's lead configuration and enumerates exactly what is included: follow-up status codes with label/colour/display order, the colour tag library, and assignable members. Its scope is distinct from sibling list tools because it focuses on configuration, not records.

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: call this tool before update_lead / set_lead_tags / assign_leads, with the reason that status codes, tag codes, and member ids are team-specific and the write tools reject unknown values. This clearly routes the agent to use this tool as a prerequisite for those write operations.

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, covering the safety profile. The description adds valuable semantic context about the token/user scoping and what isActive represents, so the agent understands that the list is scoped to the current authenticated context.

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

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

The description is two tight sentences. The first sentence states the primary purpose, and the second adds the one essential field clarification. There is no filler or repetition of schema/annotation data.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 zero-parameter, read-only listing tool with an output schema, the description provides all necessary contextual input: the exact scope of the list and the meaning of the key field isActive. Nothing an agent needs 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?

The input schema has zero properties, so there are no parameters for the description to elaborate on. The rating aligns with the baseline for zero-parameter tools, since no additional parameter guidance is needed.

Input schemas describe structure but not intent. Descriptions should explain 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 ('List') and a clear resource ('all teams (tenants) the current user belongs to'), making it obvious what the tool does. It also clarifies the meaning of isActive, which differentiates it from sibling tools such as get_active_tenant and 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 clear context for when to use the tool: when you need to list all teams belonging to the current user. It does not explicitly contrast against siblings like get_active_tenant, but the scope is unambiguous enough that an agent can select this tool without confusion.

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

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

The description discloses important behavioral traits beyond the annotations: results are scoped to the current team, newest first, and returns a compact report summary. It also warns that emails and phone numbers are masked and instructs callers to reference respondents by examineeId, which is valuable privacy-aware guidance. No contradiction with the readOnlyHint=true 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 reasonably compact and front-loaded: it states the main purpose, the returned fields, and the available filters early. The masking and examineeId warning adds length but is operationally important, so 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 an output schema exists and annotations mark the call as read-only, the description fully covers what an agent needs: scope, sort order, item content, optional filters, masking behavior, and a pointer to get_record for detail. Nothing critical 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 each parameter. The description adds a high-level grouping of filters — by form, report status, and submitted-at range — but does not add meaning beyond the schema's own descriptions.

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

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

The description states a specific verb and resource: 'List submission records (leads) of the current team, newest first.' It also lists what each item contains and supports optional filters, making the tool's purpose unmistakable. It stands apart from the sibling get_record, which is explicitly reserved for full detail.

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

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

The description gives clear context for when to use this tool: when you need a list of short submission records with filters, and it mentions the default sort order. It explicitly points to get_record for full record detail, but it does not clarify how this differs from list_leads or list_examinees among the siblings.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond the annotations: only active templates are listed, it accesses the public library, and results are ordered by usage count. These details are useful and align with the read-only annotation, adding insight without contradicting it.

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

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

The description is exactly two sentences and earns both: the first packs the resource, scope, output composition, and ordering; the second gives the workflow context. Nothing is redundant, and key integration information is front-loaded.

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

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

The listing purpose, public scope, output fields, ordering, and recommended successor tool are all stated, and the output schema covers the return structure. With optional parameters fully documented in the schema and read-only semantics declared in annotations, the description is complete for an agent to invoke and integrate the tool correctly.

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

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

Schema coverage is 100%: all 5 parameters (limit, scene, categoryId, isRecommended, titleContains) have descriptions and defaults/limits. The description does not add parameter-level meaning beyond what the schema already 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 states a specific verb and resource: 'List active templates in the public template library', and enumerates the returned fields and ordering. It clearly distinguishes itself from sibling tools by scoping to templates and pointing to create_form_from_template as the next 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?

The description gives explicit when-to-use guidance: use it to find a template, then call create_form_from_template with its id, framing this as the fastest way to build a quiz when a suitable template exists. This also implicitly tells the agent when not to use it, when no suitable template exists, while mentioning a named alternative workflow.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so this is a mutation without data destruction. The description adds useful behavioral details: it explains that the operation uses after/before to position an item, and specifically how to move to the front (target the first field) and to the end (target the last field). It also clarifies that after and before are mutually exclusive by saying 'choose either'. This goes beyond the bare 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?

The description is three sentences long and front-loaded with the core action. Each sentence earns its place: the first states the purpose, the second explains the after/before mechanism, and the third covers the front/end edge cases. It contains no fluff or repetition, making it efficient and easy to scan.

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

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

Given the tool has an output schema (which covers return values), the description need not explain those. It adequately covers the essential operational details: what to move, how to specify a relative position, and how to achieve first/last placement. It does not mention error conditions like 'code not found' or 'both after and before provided', but the schema's required fields and the explicit 'choose either' mitigate that. Overall, an agent has enough information 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%, so each parameter is already described in the schema. The description adds semantic value by explaining the relationship between 'code' (the item to move) and 'after'/'before' (the reference points), and by providing the front/end strategy. It clarifies the meaning of the parameters beyond their individual descriptions, which lifts it above the baseline 3.

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

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

The description clearly states the action ('Move an existing item'), the resource types (question, page break, display block), and the mechanism (by code, positioning relative to another field). It distinguishes from sibling tools by focusing on reordering existing items rather than creating or updating content, and it gives concrete examples for moving to the front or end.

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 implicit usage guidance by stating the tool moves existing items, which rules out creation scenarios, and explains how to achieve front/end positioning. It does not explicitly mention alternatives like insert_question or delete_question, but the mechanics of after/before and the front/end examples give the agent enough context to decide when this tool is appropriate. A bit more explicit exclusion of creating new items would push it to 5.

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

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

The description goes beyond the readOnlyHint by clarifying that the tool itself does not upload or receive image bytes, and by documenting the 5MB limit, the temporary-file lifecycle, the HTTP PUT step with Content-Type, and the required finalize step. This fully discloses the tool's role in a multi-step flow and warns about the practical upload requirement.

Agents need to know what a tool does to the 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 and dense, but the length is justified by the two-phase upload flow, the size-limit constraint, and the need for executable examples. It is front-loaded with the key mental model ('this tool does NOT receive image bytes') before giving the step-by-step workflow. It could be tightened slightly, but every included sentence serves a functional role.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 exists and the annotations cover the read-only/destructive hints, the description provides everything an agent needs to call this tool and continue the workflow. It covers prerequisites, the 5MB cap, accepted MIME types, the separation between this tool and finalize_image_upload, and even concrete curl/sips snippets for execution. 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 schema already documents all three parameters, the description adds meaningful context: fileSize is described as the size after compression and as the target of an up-front quota check, with the authoritative check deferred to finalize_image_upload. The description also ties filename, mimeType, and fileSize to the actual upload flow, which enriches the schema's literal definitions.

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

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

The description clearly identifies the tool as 'Step 1 of 2 for adding an image' to the team media library and explains that it produces a presigned upload URL rather than receiving image bytes. This distinguishes it sharply from the sibling finalize_image_upload and gives the agent an accurate mental model of the operation.

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

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

The description gives a numbered 6-step workflow covering when to call this tool, what to do before calling it (compress files over 5MB), and what to do afterward (PUT to the returned URL, then call finalize_image_upload). It also explicitly states the accepted MIME types and the rejection condition for oversized uploads, so the agent can decide correctly when 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 only carry shallow flags (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description shoulders the full disclosure burden and does so thoroughly. It reveals the attendee email side effect, the re-armed 24h reminder, the booking.rescheduled integration event, and two concrete rejection modes. There is 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 four efficient sentences ordered logically: action, prerequisite, side effects, and failure conditions. Every sentence delivers new, necessary information and none of them repeat the schema or annotations. The primary purpose is front-loaded in sentence one.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a sequential dependency, external side effects, and race-condition failures, the description covers all essential elements: the prerequisite call, the slot selection, the effects of the operation, and the cases where it will be rejected. Since an output schema is present, omitting return-value details is acceptable, leaving no notable gap.

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

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

The schema already documents both parameters with 100% coverage, including the requirement that startAt must be a slot from get_booking_availability. The description adds meaningful context beyond this baseline: the booking belongs to the current team, the acting role must be the organiser, and the startAt must be selected from that specific booking's availability call. This helps an agent choose the right values without being redundant.

Input schemas describe structure but not intent. Descriptions should explain 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 the specific action and resource: 'Move a confirmed booking of the current team to a different time, as the organiser.' It precisely limits scope to the current team and an organiser role, which distinguishes it in a glance from siblings like update_booking_status, review_booking, and get_booking_availability. An agent can tell exactly what resource is being changed 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 explicitly instructs the agent to call get_booking_availability with the bookingId first and to pick a startAt from the returned slots, which is a mandatory ordering constraint. It also states rejection conditions (slot taken, respondent already has an active booking, booking not scheduled), clarifying when the call will fail. It stops short of a 5 because it does not name alternatives for different intent (e.g., when to use update_booking_status or review_booking), but the context is very clear.

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

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

The description adds meaningful behavioral context beyond the annotations: it is a mutation (consistent with readOnlyHint=false), requires specific roles, and fails if the form is not in the trash. It does not mention any side effects like permanently deleting or overwriting data, but the annotation destructiveHint=false covers that concern.

Agents need to know what a tool does to the 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 wasted words. It front-loads the core purpose, then adds constraints in a logical order, making it easy for an agent to parse quickly.

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

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

For a single-parameter tool with an output schema and annotations, the description covers the essential operational details: what the restore does, who may perform it, and when it will error. An agent has enough information to invoke the tool correctly in the intended workflow.

Complex tools with many parameters or behaviors need more documentation. 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 documents formId with a clear description, and the tool description does not add significant parameter-level detail. With 100% schema description coverage, the baseline of 3 is appropriate; the description adds context about team scope but not about the parameter itself.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Restore a form from the trash'), the resource (form), and the scope ('current team'). It also ties directly to its inverse operation ('undo delete_form'), making its purpose unambiguous and distinguishable from sibling tools like update_form or create_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 gives clear usage context: use this to undo a deletion of a form in the current team. It specifies permission requirements and an error condition, but does not explicitly name alternative tools for cases like creating a new form or editing an existing one, so it stops short of full 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 discloses real side effects beyond the write annotations: it sends the attendee a confirmation with the address, sends a 'not approved' note, and can override team-level meeting settings for a single booking. This is exactly the behavioral context an agent needs for a side-effecting approval/decline workflow.

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

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

Every sentence adds operational value: main action, notification behavior, constraints, permissions, and optional overrides. It is compact, front-loaded, and contains no redundant statements.

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

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

Together with the complete input schema and the output schema, the tool description covers the state machine (pending/reviewable, passed-only-decline), authorization scope, external messaging effects, and optional parameters. Nothing needed to safely call the tool 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 schema already documents all five parameters at 100% coverage, so the description adds only modest extra meaning: approval-path vs decline-path mapping and fallback to team-level settings. This matches the baseline for a fully schema-documented parameter set.

Input schemas describe structure but not intent. Descriptions should explain 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 precise action verbs: 'Approve or decline a pending booking request.' It names the resource, the target state after approval, and the notification behavior, which makes it easy to distinguish from siblings like list_bookings or reschedule_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?

The description gives clear eligibility conditions: only pending bookings, only team owner/admin/lead owner, and already-passed meetings can only be declined. It does not explicitly mention when to use a sibling tool instead, but the stated constraints make the intended use 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 carry no safety hints (all flags false), so the description bears the full behavioral burden — and it delivers: replacement semantics, preservation of omitted settings, code-stability rule, removal constraints for dimensions referenced by question dimensionScores or report.formula, empty-array clearing behavior, and the unsupported form type. 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?

Seven sentences, each carrying distinct information — core semantics, stability rule, scene requirements, failure mode, clearing behavior, prerequisite, exclusion — with zero redundancy. The core behavior is front-loaded in the first sentence, and the density is justified by the tool's genuine complexity.

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

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

For a tool with 5 parameters, a nested dimensions array, scene-dependent behavior, and an output schema, the description covers mutation semantics, partial-update behavior, failure modes, clearing, prerequisites, and exclusions. An output schema already exists so return values need no explanation. 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% with rich per-field descriptions, so the baseline is 3. The description adds meaningful contextual semantics beyond the schema: the code-stability rule (same name preserves existing code), the automatic summation of choices[i].dimensionScores and when a formula is actually needed, and the removal constraint linking to report.formula. These are behavioral clarifications that the schema's per-field docs do not fully convey.

Input schemas describe structure but not intent. Descriptions should explain 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 — 'Set the multi-dimension analysis (form.report.dimensionAnalysis) of a form' — and precisely describes the mutation semantics: replacing the dimension list while preserving omitted overallAnalysis settings. This clearly differentiates it from general form setters like update_form and update_form_settings among the siblings.

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

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

Provides explicit when-to-use scene guidance (knowledge_quiz requires fieldCodes; scored_quiz makes formula optional with automatic dimensionScores summing), a concrete prerequisite ('Call get_form first to read the question and dimension codes'), and a clear when-not exclusion ('Not supported for random_knowledge_quiz forms'). An agent knows exactly when and how to invoke this tool.

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

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

Even though the destructiveHint and readOnlyHint annotations already indicate this tool mutates data, the description goes further by disclosing that replace overwrites the whole tag set, that add/remove prevents wiping other leads' tags, that tag codes must exist in the library, and that changes appear on each lead's timeline. 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?

Every sentence in the description is useful and dense. The core operation is stated first, followed by batching, mode semantics, tag validation, and the timeline side effect. It gives high value without unnecessary 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?

With an output schema present, the description does not need to explain return values. It covers the batching limit, all three modes, tag source and validation, stale-code behavior for remove, and the timeline effect. This is complete enough for an agent to select and call the tool correctly without needing lookups beyond the referenced tag library.

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

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

The schema has 100% field coverage, so the baseline is 3, but the description substantially adds meaning: it explains leadIds should be batched, tags come from a specific library, remove accepts stale codes, and why the mode choices matter. This guidance is not derivable from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain 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 ('set') and resource ('colour tags on one or more leads of the current team'), immediately clarifying what the tool does. It also explains the scope limits and the three modes, which distinguishes it from generic lead-update tools like update_lead.

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 operational guidance: pass all lead IDs in a single call, never loop, and use replace vs add/remove based on whether you are editing one lead or many with different tags. It also directs users to list_lead_settings.tags for valid codes. It stops short of explicitly contrasting with sibling tools such as update_lead, so it gets a 4 rather than a 5.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description adds meaningful behavioral context: the switch is persistent across sessions and requires team membership. This communicates the side-effect nature of the tool 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 two short sentences with no filler. The most important behavioral facts—what it does, persistence, and membership requirement—are front-loaded 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?

For a single-parameter switching tool with an output schema and annotations, the description covers the essential operational context: target tenant, persistence, and membership requirement. It could mention what happens when the caller is not a member, but the core guidance for a successful call is present.

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

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

The parameter schema fully describes tenantId and even suggests list_my_tenants for discovery, so the tool description itself does not add additional parameter-level semantics. This matches the baseline expectation for high schema coverage.

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

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

The description states a specific verb ('Switch') and clear resource ('active team/tenant') with the exact effect: changing the tenant for the token. It distinguishes itself from related read/list tools by focusing on switching rather than querying.

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 useful context: the change persists across sessions and the caller must be a member of the target team. It also includes a prerequisite via the parameter description referencing list_my_tenants, though it stops short of explicitly naming alternatives or when not to use 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?

Given no annotations providing safety details, the description carries the full burden, and it delivers: it discloses cancellation sends attendee email and fires booking.cancelled, while completed/no_show are internal and contact no one. It also states precondition requirements, going well 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 dense, front-loaded, and contains no filler. The core action and allowed states come first, then preconditions and side effects, then the routing note about review_booking. Every sentence adds 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?

The tool has only two parameters and an output schema. The description covers allowed transitions, preconditions, side effects, and the boundary versus review_booking. There is no missing guidance an agent needs to invoke this safely and correctly.

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

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

Schema description coverage is 100% and the schema already documents both status meanings and bookingId. The description does not add new parameter-level meaning beyond what the schema provides, though it does contextualize behavior around them. 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 uses a specific verb ('Close out a confirmed booking') and enumerates the exact status transitions: completed, no_show, or cancelled. It also explicitly distinguishes itself from review_booking. An agent can immediately understand what this tool targets and how it differs from siblings.

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 when-to-use conditions are explicit: it only works on bookings with scheduled status, completed/no_show require the meeting to have started, and pending requests should use review_booking instead. This is precise, actionable guidance that prevents misuse and correctly routes to the 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 declare destructiveHint=true, and the description over-delivers by explaining exactly what is dangerous: customData REPLACES the whole object, masked phone values will be rejected, and re-sending read values can wipe or corrupt phone fields. It also discloses that email/tenant/examineeId cannot be changed, which goes well beyond the annotation hints.

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

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

The description is dense but each clause earns its place: it identifies the identifier, lists editable and immutable fields, and gives a critical operational warning. Slightly on the long side, but the length is justified given the destructive behavior that the agent must understand to avoid data loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a nested-object parameter, a destructive warning, and an output schema, the description covers all needed decision points: which fields are mutable, what validation applies to customData, and the replace semantics. Nothing essential is missing 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?

The input schema already provides descriptions for every parameter, including enum options, regex/E.164 requirements, and detailed customData semantics. The description reinforces the replacement semantics and the don't-resend warning, which is valuable, but it adds marginal net value because the schema already carries the full load (100% coverage).

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

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

States a specific verb and resource ('Update an examinee'), identifies it by examineeId, and clearly names which fields are editable vs immutable. The description also references list_examinees as the source of the business ID, which helps distinguish its purpose from sibling tools like get_examinee and list_examinees.

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 lists editable fields (name, status, customData) and immutable fields (email, tenant, examineeId), and warns against re-sending customData read from get_examinee. It also explains that customData must only contain values the user provided, giving concrete when-to-use rules and a critical exclusion.

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 behaviors: report and openGraph merge by sub-key, systemText is replaced wholesale, empty strings clear image/og fields, language changes are restricted while translations exist, scene is never changeable, outcome removal can be rejected, and landingImage only sets the image—it does not toggle the landing page. These are exactly the behaviors an agent needs to predict side effects.

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

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

The description is dense but efficient: it starts with the field inventory and then groups related behavioral rules in a logical order (images, merge semantics, scene constraints, sub-resource routing). It is a single block of text without bullets or headings, so slightly harder to parse, but every sentence carries needed guidance and 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 complex tool with 11 parameters, nested report/openGraph objects, scene-specific rules, and an output schema, the description plus the fully-described schema cover media handling, merge semantics, clearing behavior, language restrictions, and alternative sibling tools. The output schema handles return-value expectations, so nothing critical is missing for safe invocation.

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

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

Schema coverage is 100%, so the schema already documents every parameter well. The description adds cross-parameter semantics not obvious from individual schemas: the shared media-source convention (finalize_image_upload ID, media URL, or empty string), the merge-vs-replace distinction between report/openGraph and systemText, and the scene-specific outcome behavior. That is valuable added meaning on top of the schema.

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

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

The description opens with a specific verb+resource statement — 'Update a form of the current team' — and explicitly enumerates the fields it handles: title, description, isActive, flagImg, landingImage, theme, report, openGraph, language, systemText. It also distinguishes itself from sibling tools by directing questions to add_question/update_question/delete_question/move_question and dimensionAnalysis to set_dimension_analysis. This makes the tool's 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 clearly identifies the form-level update use case and explicitly tells agents which sibling tools to use for sub-resources (questions, dimensionAnalysis), so the agent is routed correctly for those cases. It does not explicitly compare with update_form_settings, but the precise field list and sub-resource routing make the intended usage context clear.

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

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

Annotations already signal this is a mutating call (readOnlyHint=false), and the description adds meaningful non-obvious behavior: partial updates, the lead-capture trade-off for submissionAccess/reportGateRequireCode, and the sharing/booking effects. It does not cover side effects like slug breakage, but the schema already documents that.

Agents need to know what a tool does to the 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 the tool has 10 parameters and nested objects. The first clause front-loads the main purpose and sibling distinction, and the long list of editable fields is dense rather than padded.

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