RooQuiz

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false) but say nothing about idempotency or limits. The description adds high-value behavioral context: it explicitly states the operation is not idempotent, warns that a timed-out call may still have succeeded, and prescribes checking before retrying. It also discloses the Free-plan 50-question cap (with what does and does not count) and when to configure banks in the web app.

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

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

The core action is front-loaded in the first sentence and each clause carries information, but the body is one very dense paragraph that overlaps heavily with the schema's own FIELD APPLICABILITY block (type-availability-per-scene, scoring rules). A reader must parse a long run-on to reach the idempotency warning buried at the end, which is arguably the most operationally important 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 29-parameter tool with nested objects, the description covers the essential non-schema facts an agent needs: type applicability, scene-based scoring rules, plan limits, and the non-idempotency/retry hazard. An output schema exists, so return-value documentation is unnecessary and not missed.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description adds cross-parameter guidance the schema doesn't give: which fields are ignored for Breaker ("only formId + type are needed, other fields are ignored"), DropDown's preference over SingleCheck/MultiCheck past 20 choices, and the distinction between scored data-collection fields and scored answers. These are semantic relationships between parameters, not restatements.

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 opening sentence gives a specific verb and resource ("Append an item to the end of a form") and the scope "to the end" implicitly distinguishes it from the sibling insert_question. It then enumerates what `type` can be (question, Breaker, display block), so an agent knows exactly what is being created. It never names insert_question/move_question, so sibling routing is left to inference.

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 rich guidance on which question types to choose and when (e.g. "prefer DropDown over SingleCheck/MultiCheck past 20 choices"), plus plan limits and retry behavior. However, it offers no guidance on when to use this tool versus the sibling insert_question, move_question, or update_question, which is the primary routing question for an agent. Usage is implied by the append-to-end semantics rather than stated.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=true, but the description adds valuable behavioral context: 'Each actual change is recorded on the lead's timeline' and describes the aggregated notification and email behavior, including that reassigning the same owner does not trigger another notification. This goes beyond the annotations and helps the agent understand side effects and user-facing impacts.

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

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

The description is somewhat long but every sentence provides useful guidance: purpose, batching rule, assignee requirements, unassign method, and side effects. It is front-loaded with the core action and then provides necessary operational details. It is not overly verbose given the amount of information needed for correct usage.

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

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

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

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

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

Schema coverage is 100% and both parameters already have detailed descriptions (e.g., 'The member userId to assign to, or "me"... Omit (or pass null) to clear the assignee.'). The description repeats these details but adds no new parameter-specific information beyond the schema. The batching instruction (up to 50) is also already in the schema's maxItems. Therefore, the description adds minimal extra parameter meaning.

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

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

The description clearly states the action: 'Assign one or more leads of the current team to a member, or clear the assignee.' This is a specific verb (assign) with a specific resource (leads) and an additional action (clear). It distinguishes itself from siblings like set_lead_tags or update_lead by focusing on the assignment/ownership change.

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

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

The description provides explicit usage rules: 'Pass every lead id in a single call (up to 50) — do not loop one call per lead.' It also specifies prerequisites (assignee must be an active non-viewer member, see list_lead_settings.assignableMembers) and explains how to unassign (omit/null). It does not explicitly name alternative tools for the same operation, but it points to a sibling for prerequisite info, and the 'do not loop' instruction is a clear when-not-to-do.

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

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

Annotations only declare readOnlyHint=false / destructiveHint=false / openWorldHint=true; the description adds genuinely non-obvious behavior: the Free-plan 50-question cap (with what does and doesn't count), the fact that only the primary language is created, and an explicit non-idempotency warning about timeouts and duplicate creation. That is exactly the kind of operational context annotations cannot carry.

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

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

The core action and the one-call-vs-follow-up choice are front-loaded, and the dense middle is information-bearing rather than padding. It is long, but each sentence (scene requirements, plan limits, idempotency) earns its place rather than duplicating the schema.

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

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

For a 9-parameter tool with nested objects, 100% schema coverage, and an output schema, the description covers all the decision-critical extras: scene-dependent requirements, one-call creation strategy, language handling, plan limits, and retry safety. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning: report.outcomes is REQUIRED at create time for outcome_quiz, dimensions must be defined with codes/formulas in the same call, and structuredContent.fields must be read before filling report.formula on follow-up. It clarifies sequencing rather than restating field docs.

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 with scope ('Create a form in the team this token is bound to'), and immediately differentiates itself from siblings by naming create_form_translation, update_form and set_dimension_analysis as the follow-up paths. An agent can distinguish it from update_form or create_form_from_template without opening a 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?

Gives clear when-to-use context: pass questions and report in one call 'instead of following up with per-question calls', and add languages later with create_form_translation rather than here. Scene-specific rules (outcome_quiz requires outcomes at create time; scored_quiz dimensions must be defined in the same call) direct usage well. It stops short of naming exclusions versus siblings like create_form_from_template or duplicate_form.

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

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

Annotations indicate a non-read-only, non-destructive, open-world operation, but the description adds substantial behavioral detail: it clones template structure, scoring/report configuration, visual settings, and all language versions in one call. Critically, it warns that the call is not idempotent and that retrying after a timeout may create duplicates. This goes far beyond the annotations.

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

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

The description is four sentences, each earning its place: core action, what is cloned, post-creation workflow, and idempotency warning. It is front-loaded with the main purpose and the additional caveats are critical rather than filler.

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

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

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

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

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

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

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

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

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

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

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

The description gives explicit when-to-use guidance: 'This is the fastest way to build a quiz when a suitable template exists — prefer it over building from scratch with create_form.' It also explains the post-creation workflow with update_form / update_question and provides a concrete prerequisite via list_templates. This is strong routing guidance relative to sibling tools.

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

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

Annotations declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the safety burden is light. The description adds real behavioral context beyond that: the source text is cloned as an initial draft, the result is returned immediately, and codes must stay identical to the source. It stops short of describing failure modes or partial-state behavior.

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

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

Three dense sentences, all front-loaded with the action and outcome before the constraints. Every clause carries a distinct, useful instruction with no filler.

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

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

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

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

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

Schema coverage is 100% and the language enum plus 'must differ from primary language' are documented in the schema. The description adds the uniqueness rule (one translation per language) that the schema does not state, giving genuine extra semantic meaning.

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

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

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

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

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

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

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

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

The description clearly states this is a destructive/state-changing operation ('delete', 'move to trash', 'auto-purged'), but the annotations declare readOnlyHint: true. This is a direct annotation contradiction, so the behavioral transparency score must be 1.

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

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

Three dense sentences front-load the action, then explain recovery and permissions. No filler, and each sentence adds operational value.

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

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

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

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

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

The schema fully documents the only parameter formId as a UUID, so the description adds little about parameters. The described team/owner context is about authorization rather than the parameter's meaning.

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

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

The description states a specific action ('Move a form into the trash / soft delete') on a specific resource (form) within a context ('current team'). It lucidly distinguishes this soft-delete operation from a hard delete and names the recovery path via restore_form, making the tool's purpose unmistakable against siblings like delete_form_translation.

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

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

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

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

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

Annotations already mark this as destructive, but the description adds meaningful behavioral details: submission records are anchored to the source form and not deleted, and reports for historical records in the deleted language fall back to source text. It also notes the primary language cannot be deleted, which is a significant constraint. These go beyond the annotations and inform the agent of side effects.

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

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

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

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

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

For a simple delete operation with an output schema present and annotations covering destructiveness, the description covers the key caveats: submissions are preserved, reports fall back, and primary language is excluded. It does not address potential errors (e.g., deleting a nonexistent language) or idempotency, but these are minor for this tool's complexity. Overall it is nearly complete.

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

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

The schema descriptions for both formId and language are sufficient (100% coverage). The description does not add extra parameter semantics; it only restates that a language is being deleted and mentions the primary language restriction, which is not directly tied to the parameter details. Baseline 3 is appropriate.

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

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

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

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

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

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

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description appropriately focuses on additional behavior: the types of items supported (including page breaks and display blocks) and the rule that deleting the last item is allowed. This adds context beyond the annotations and does not contradict them.

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

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

Two tightly written sentences with no redundancy. The purpose is front-loaded, the item types are listed, and the edge case (empty shell) is stated. Every word earns its place.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a mutation tool with an output schema present, the description covers all essential decision factors: what is cloned, what is not, the use case, and the retry caveat. Nothing an agent needs to safely invoke it is missing; the output schema handles return-value details.

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

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

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

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

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

The description opens with a specific verb-resource pair, 'Duplicate a form in the current team,' and enumerates exactly what is cloned (structure, scoring, report, visual settings, translations) and what is not (submissions, sharing, integrations, ban state). This clearly distinguishes it from siblings like create_form or create_form_from_template, which create new forms from scratch or templates.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The input schema already documents all 4 parameters with good descriptions at 100% coverage. The description reinforces that key, filename, and mimeType come from the prepare step, but adds limited new parameter-level meaning beyond what the schema provides.

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

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

The description clearly identifies this as step 2 of a 2-step upload flow, specifying the exact action (verify, record, return media id + public URL) and distinguishing it from prepare_image_upload and update_form. An agent can immediately understand what this tool does and how it fits.

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

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

It explicitly states when to call this tool ('AFTER you have PUT the file to the uploadUrl') and what to do next ('call update_form with flagImg or landingImage'), providing clear sequencing and pointing to the relevant sibling alternatives.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states the verb 'Return' and the resource 'team (tenant) this token is currently operating against,' with the additional scoping note that all write tools default to this tenant. This makes the tool's purpose unambiguous and implicitly distinguishes it from tenant-switching tools like switch_active_tenant.

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

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

The description gives concrete contextual usage: it explains that this is the token's operating context, that write tools default to it, and specifically advises checking the examineeSignupDisabled flag before attributing sign-in problems to a quiz. It doesn't explicitly enumerate when not to use it, but the usage context is clear enough.

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

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

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

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

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

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

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

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

Given that an output schema exists and read-only annotations already cover safety, the description covers all necessary invocation context: availability computation, enabled:false handling, bookingId semantics, the precondition for reschedule_booking, and server-side range limits. Nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%, so the schema documents all three parameters. The description reinforces bookingId's role by explaining the current slot is 'not counted as taken', but it adds little beyond the schema's own description for that parameter and nothing new for fromDate/toDate. This meets the baseline without exceeding it.

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

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

The description opens with a specific verb and resource: 'Read the current team's bookable time slots in a date range'. It further distinguishes the tool from siblings like list_bookings by explaining slots are 'computed from the team's weekly booking rules minus what is already taken', making the availability concept unmistakable.

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

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

The description gives explicit guidance: pass bookingId for rescheduling and 'always call this before reschedule_booking' because an out-of-range start time is rejected. It does not explicitly state when to prefer list_bookings or other sibling tools, but the availability-versus-bookings distinction is sufficiently clear for routing.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description makes the intended use clear: retrieve full details for a single examinee by business ID, with the additional hint that the ID is the one shown in list_examinees. It does not explicitly name alternative tools or exclusion conditions, so it stops short of a 5, but the context is unambiguous.

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

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

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

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

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

The description is two sentences with no filler. The main purpose and output scope are front-loaded, and the second sentence adds clarifying output semantics rather than repeating schema content.

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

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

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

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

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

Schema description coverage is 100%, and the schema already explains id, includeFields, and includeReport with their defaults. The description implicitly relates fields[] and report to the include flags, but it adds no additional parameter semantics beyond what the input schema already provides.

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

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

The description opens with a specific action and resource: "View one form of the current team in full," which clearly distinguishes it from list_forms and get_form_stats. It also specifies what "full" means by naming fields[] and the report configuration, so an agent knows exactly what this tool returns.

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

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

The description gives clear context: use this when you need one complete form including its questions and report configuration, not just a form listing or translation. It does not explicitly state when-not against related tools like get_form_translation or list_forms, but the context is strong enough for a retrieval tool.

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

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

Annotations already mark it read-only and non-destructive; the description reinforces this by saying 'Read' and adds useful behavioral context—telemetry source, current-team scope, stage semantics, and the special counting rule for leadCaptured. It does not undermine or contradict the annotations.

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

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

The definition is front-loaded with the core action and resource, and both sentences carry useful information. The first sentence is dense and somewhat run-on, but the details are relevant enough to justify their inclusion.

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

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

With an output schema present, the description need not explain return values, and it covers the data source, stages, channel breakdown, counting caveat, and intended use. Minor ambiguity in 'embedded flag' and the lack of explicit cross-references to sibling tools keep it from being fully complete.

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

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

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

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

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

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

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

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

It explicitly states the intended use ('Use this to find where respondents drop and improve conversion'), telling an agent when to prefer this tool. It does not name alternative tools or exclusion conditions, so it stops short of full when/not guidance.

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

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

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

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

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

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

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

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

For a read-only 4-parameter tool with an output schema, the description supplies exactly the missing context: what the payload is for, how a parameter changes the payload, and which sibling performs the write. Nothing an agent needs before calling is absent.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is a single, information-dense sentence that front-loads the key action and scope, then uses a colon to introduce a list of the included statistics. While long, each item adds substantive value and there is no redundancy. It is efficiently structured without extraneous filler, but could potentially be split into two sentences for readability without losing meaning.

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

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

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

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

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

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

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

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

The description clearly states the action ('Read submission statistics for a form') with specific scope ('in the current team over the last N days') and enumerates the exact data dimensions returned (KPIs, daily trend, channels, UTM combos, login types, device breakdown, per-question distributions). It is specific enough to distinguish from related siblings like get_form_funnel or get_form without ambiguity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100% and the enum is documented, so baseline is 3. The description adds genuine meaning tied to the language parameter: it must already exist, otherwise the call errors and you must create it first. No syntax details beyond the schema are added, but the precondition is a real semantic gain.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the schema already documents all four parameters well, giving a baseline of 3. The description adds value by translating the boolean flags into the exact content they include (submission history, internal comments, change timeline) and by emphasizing the leadId/examineeId reference rule. This is useful extra semantic guidance, though the schema already carries the core meaning.

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

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

The description opens with a specific verb and resource: 'View one lead of the current team by leadId.' It then enumerates the payload contents (follow-up status, assignee, tags, respondent block, next booking), making it unambiguous what this tool returns and clearly distinct from list-oriented or examinee-focused siblings. It leaves no doubt that the resource is a single lead, not a record or examinee.

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

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

The description gives clear contextual guidance: the lead must belong to the current team, and lookups must use leadId/examineeId rather than a masked email. It also clarifies the optional include flags behavior. However, it does not explicitly state when to prefer get_lead over sibling tools like get_examinee or list_leads, so it stops short of full routing guidance.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false) but say nothing about limits or retry behavior. The description adds plan-limit detail (Free caps at 50 questions, with the counting rule for breakers/statements/carousels/random slots) and a strong non-idempotency warning that a timed-out call may have succeeded, so blind retries create duplicates. This is exactly the beyond-annotations context an agent needs.

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

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

Four sentences, all load-bearing, and the core positioning mechanics are front-loaded before plan limits and the idempotency caveat. No repetition of schema-declared field details.

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

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

Given an output schema exists, return values need no explanation, and the sprawling per-type/scene field rules are already carried by the schema's own description. The tool-level description covers precisely what structured fields cannot: positioning semantics, the sibling alternative, plan caps, and retry safety.

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 3 baseline is in play, but the description adds positioning semantics the schema only sketches: it explains that after/before take a field code, where to obtain that code, and the front-insertion convention. It also flags the type-driven applicability of content/items, which is useful framing even though the schema's own description elaborates it.

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

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

States a specific verb (insert) plus the resource and the full range of item kinds it accepts (question, page break, display block), and names the sibling add_question for the distinct end-insertion case. An agent can distinguish this from add_question, move_question and update_question 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?

Explicit when/when-not routing: 'To insert at the end, use add_question' names the alternative and the condition that selects it, and 'To insert at the very front: before references the first field's code' covers the edge case. It also states the source of valid code values (get_form's field.code), leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds valuable context beyond these: it explains the side effects ('pending membership is created immediately and an invitation email with a join link is queued'), the fact that the link/token is never returned, and role restrictions. This goes beyond the annotations to set accurate expectations, without contradicting them.

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

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

The description is longer than minimal but every sentence carries essential information: action, side effects, restrictions, failure conditions, and contextual preparation. It is front-loaded with the core purpose and then expands logically. While it could be trimmed slightly, the density of useful content justifies the length.

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

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

Given the tool's side effects and role-based restrictions, the description covers all necessary aspects: when to use it, prerequisites, failure modes, and the non-return of sensitive data. An agent can correctly invoke this tool without needing to infer anything beyond what is stated, making it fully complete for its complexity.

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

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

Schema coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds value by clarifying the meaning of each role enum value: 'viewer' is read-only, 'admin' manages the whole team, and 'owner' is explicitly excluded. It also confirms the default for 'role'. This enhances the schema without redundancy.

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

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

The description clearly states the action and resource: 'Invite someone to the active team (tenant) by email.' It specifies the exact scope and distinguishes it from sibling tools like switch_active_tenant and list_my_tenants by focusing on the invitation action. The verb 'invite' and object 'team' are precise, making the tool's purpose unmistakable.

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

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

The description provides explicit when-to-use guidance, including role requirements ('Only the team owner or an admin can invite'), failure conditions ('Fails if the email is already a member...'), and how to prepare the correct context ('use list_my_tenants / switch_active_tenant to change teams first'). This is comprehensive and leaves no ambiguity about when or how to invoke the tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond that: the API returns earliest first, descriptions fields per item, masks attendee contact info, and indicates the 'pending' status represents an unapproved booking. This adds meaningful context without redundancy or contradiction.

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

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

The description is compact and front-loads the primary action and scope. All sentences contribute meaningful context: sorting, returned fields, filters, typical use, and attention-masking. It could drop the slightly redundant 'list' wording, but overall it earns its place without significant bloat.

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

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

With a full input schema, an output schema, and clear annotations, the description adds what the agent still needs: the meaning of the 'pending' status, the masked/contact-handling behavior, and how to reference a booking by bookingId. Combined with the structured data, the description is sufficient for an agent to select and invoke the tool correctly.

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

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

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

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

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

The description clearly identifies the tool as listing 1:1 bookings for the current team, specifies the sort order (earliest first), and enumerates what each item contains. It also mentions it filters by status, quiz, respondent, and time range, which distinguishes it from generic list tools and the related booking mutation tools.

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

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

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

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

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

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

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

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

The description is concise and front-loaded: two sentences that first state the core purpose, then provide supplemental context (sensitive fields, examineeId unmasking, pointer to get_examinee). Every sentence adds distinct value with no redundancy.

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

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

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

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

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

The input schema already documents all three parameters with descriptions (limit with default/max, search as fuzzy match, status as enum). The description adds no additional parameter-specific meaning, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb (list), the resource (examinees/respondents), the scope (current team), and the ordering (newest first). It explicitly distinguishes from get_examinee by naming the alternative for full detail, so an agent can select the right tool without ambiguity.

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

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

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

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

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

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

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

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

The description is two sentences, each earning its place: the first states the core action and scope, the second conveys ordering, content omission, and the pointer to get_form. There is no redundancy or filler.

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

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

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

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

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

The input schema already documents all three parameters with descriptions and covers 100% of the parameters, so the description does not need to repeat them. It adds no extra semantic detail about the parameters, but none is needed. The baseline of 3 is appropriate here.

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

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

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

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

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

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

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

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

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

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

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

Two sentences, no fluff. The first sentence states the action and the return fields; the second clarifies an important edge case (primary language not included). Every sentence earns its place.

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

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

The tool has a single required parameter, a full output schema, and annotations covering safety. The description explains what is returned and what is excluded. It could mention pagination or ordering, but for a simple list operation with an output schema, this is nearly complete.

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

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

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

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

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

The description clearly states the tool lists existing language versions (translations) of a form, and explicitly distinguishes it from get_form by noting the primary language is not included. This differentiates it from siblings like get_form_translation and create_form_translation.

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

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

The description implies when to use this tool: when you need an overview of all translations of a form. It also clarifies that the primary language is handled elsewhere (get_form.language), which helps an agent avoid using this tool for the primary language. It doesn't explicitly name alternatives like get_form_translation, but the context is clear enough.

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

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

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

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

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

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

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

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

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

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

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

The schema already describes all 10 parameters (100% coverage), so the requirement is low. The description still adds value by explaining the identity rules ('reference a lead by leadId, a respondent by examineeId'), clarifying the team-defined vocabulary, and noting keyword search works against unmasked server-side values. Good but not essential.

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

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

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

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

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

It explicitly gives a prerequisite: 'call list_lead_settings first' to obtain valid status/tag codes and warns 'never guess.' That is solid procedural guidance. It does not, however, spell out when to pick list_leads over other list variants (e.g., list_records or list_examinees), so it falls just short of full score.

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

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

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

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

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

The description is two sentences with no redundancy. The first sentence states the core purpose and enumerates the returned items; the second sentence gives critical usage guidance and rationale. It is front-loaded with the primary action and uses every word effectively, exceeding the minimum necessary information.

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

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

Given the tool has no parameters, has an output schema (as indicated in context signals), and annotations cover read-only and non-destructive behavior, the description is fully sufficient. It explains what the tool returns, why it should be called before specific write tools, and the team-specific nature of the data. An agent can call this tool correctly without any additional information beyond what the schema and annotations already provide.

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

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

The tool has zero parameters, so there is nothing to explain. Baseline for 0 params is 4, and the description doesn't mention parameters at all, which is appropriate. It focuses entirely on the return value and usage context, not requiring any parameter documentation.

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

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

The description clearly states it reads the team's lead configuration, enumerating the specific elements (status codes with label/colour, colour tag library, assignable members). It uses an explicit verb ('Read') and resource ('lead settings'), and differentiates itself from sibling write tools by framing itself as the prerequisite read for update_lead, set_lead_tags, and assign_leads. This makes the tool's purpose unambiguous.

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

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

The description explicitly instructs to 'Call this before update_lead / set_lead_tags / assign_leads' and explains why: status codes, tag codes, and member ids are team-specific, and write tools reject unknown values. This provides clear when-to-use guidance and implicitly states when not to use it (no need to call for other purposes). It also points to alternative write tools that require this information.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious context by scoping results to the current user's memberships and explaining the isActive flag, which goes beyond the annotations without contradicting them.

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

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

Two tight sentences deliver purpose, scope, and key field semantics with zero waste. The most important information comes first.

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

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

With no parameters, a read-only annotation, and an output schema present, the description fully covers what an agent needs to call the tool correctly. It even clarifies the ambiguous tenant/team terminology and the isActive field.

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

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

The tool has zero parameters, and the schema coverage is trivially 100%. Per the baseline for parameterless tools, a 4 is appropriate; there is no param info needed and the description adds relevant semantic context.

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

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

States a specific verb ('List') and resource ('all teams (tenants) the current user belongs to'). The isActive clarification further distinguishes this from get_active_tenant and switch_active_tenant, making the purpose unambiguous.

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

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

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

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

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

Annotations already cover readOnlyHint and destructiveHint, so the safety profile is known. The description adds behavior beyond annotations: records are sorted newest first, PII such as emails and phone numbers is masked in answers, and records must be referenced by examineeId. This meaningfully enriches the agent's expectation of the tool's behavior.

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

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

The description is three sentences and front-loads the primary purpose, then gives filters and guidance. It is fairly dense but avoids redundancy, with each sentence serving a distinct role. It could be trimmed slightly, but it earns its place.

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

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

Given that the tool has 6 optional parameters, a full output schema, and safe-read annotations, the description covers ordering, item composition, filter dimensions, a reference/masking subtlety, and points to the more detailed single-record tool. There is no substantial gap for an agent to call this correctly.

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

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

Schema description coverage is 100%, so the parameters are already well defined. The description adds extra semantics by grouping since/until as a 'submitted-at range' and warning that email/phone answers return masked, reinforcing reference by examineeId. This goes beyond just restating the schema, though most parameter details remain in the schema.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description gives explicit guidance on when to use this tool: to find a template, and then directs the agent to call create_form_from_template with the template id. It also frames this as the fastest way to build a quiz when a suitable template exists, implicitly telling the agent to prefer this path over directly creating a form.

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

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

Annotations already indicate readOnlyHint=false (mutation) and destructiveHint=false, so the description adds context about how the move works (after/before, front/end). It doesn't disclose potential side effects like reordering implications or error handling, but given annotations, the added value is moderate. No contradiction with annotations.

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

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

The description is three sentences, front-loaded with the main purpose and mechanism. It includes all essential information without redundancy or fluff. Each sentence contributes value, making it efficient and easy to parse.

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

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

The tool has a moderate complexity (moving items with after/before and front/end logic), and the description covers the core usage scenarios. An output schema exists, so return value details are not needed in the description. It doesn't mention edge cases like invalid codes or same-position moves, but for an agent, the provided guidance is sufficient to invoke correctly in common cases.

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

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

Schema coverage is 100%, so all parameters are documented. The description adds meaningful semantics beyond the schema: it clarifies that 'after' and 'before' are mutually exclusive, and explains how to reference the first/last field for front/end moves. This enriches understanding of the parameters, especially the interplay between code, after, and before.

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

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

The description clearly identifies the verb 'move' and the resource 'existing item (question, page break or display block)' and specifies the mechanism (by code, referencing another field's code). It also differentiates from sibling tools like add_question, update_question, and delete_question by focusing on reordering, and gives explicit front/end usage. This is specific and unambiguous.

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

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

The description provides explicit usage instructions: choose either after or before, and explains how to move to the front (before the first field's code) or end (after the last field's code). It implies the tool is for repositioning existing items, which distinguishes it from add/update/delete. However, it doesn't explicitly state when not to use it or compare with alternatives, but the context is clear enough.

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

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

Annotations only mark readOnlyHint=false and destructiveHint=false, so the description carries the burden of behavioral disclosure. It adds substantial detail: the presigned URL is short-lived, uploads over 5MB are rejected, the team storage quota is checked up front, and the caller must send a matching Content-Type header. This fully explains side effects and constraints without contradicting the annotations.

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

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

The description is long, but every sentence carries load-bearing operational information and the structure is a clear numbered workflow with concrete examples. The key behavioral fact (returns a presigned URL, does not accept bytes) is front-loaded. It is not minimal, but the length is justified by the complexity of the two-step upload.

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

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

For a multi-step upload involving local temp files, compression, MIME constraints, size caps, quota checks, HTTP PUT semantics, and a follow-up finalization tool, this description is complete. It even includes cleanup and tells the agent exactly how to call the sibling next. Since an output schema exists, not describing return values in prose is acceptable.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds operational meaning beyond the schema: fileSize is optional and refers to the file after compression, it is checked early against the 5MB cap and quota, and the authoritative size check happens in finalize_image_upload. It also clarifies that filename is for admin display and mimeType must match the uploaded Content-Type.

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

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

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

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

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

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

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

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

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

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

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

The description is front-loaded with the core action and each major behavioral note earns its place. It is slightly long and a few parameter constraints are restated from the schema, but the extra detail is valuable rather than filler.

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

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

Given the tool is destructive, mutating, and externally observable via annotations, the description covers prerequisites, side effects, failure conditions, and retry safety. Since there is an output schema, not explaining the return value is acceptable; the agent has everything needed to call and verify this tool safely.

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

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

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

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

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

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

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

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

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

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

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

Beyond the annotations, the description reveals permission requirements (owner/admin only), scope (current team), and failure behavior (errors if form is not in trash). This goes well beyond the readOnly/destructive hints and gives the agent concrete expectations.

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

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

A single sentence that front-loads the action ('Restore'), scope ('from the trash in the current team'), relationship ('undo delete_form'), access restriction, and error behavior. No filler.

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

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

For a one-parameter restoration action with an output schema and annotations present, the description covers what, where, who can perform it, and when it errors. There is no meaningful missing context for an agent to invoke it.

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

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

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

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

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

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

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

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

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

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

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

Beyond the annotations' destructiveHint, the description discloses the real-world side effects: approving confirms the meeting and emails the attendee the meeting address, while declining sends a 'not approved' note. It also exposes the constraint about already-passed meeting times, which is valuable behavioral information not present in the annotations.

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

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

The description is compact, front-loaded with the central purpose, and each sentence contributes distinct information: decision semantics, side effects, status constraints, optional parameters, and permissions. There is no filler or redundancy.

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

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

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

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description adds context about approval-time link/instructions falling back to team settings, but this is largely mirrored in the schema, so it does not substantially elevate meaning beyond the input schema.

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

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

The description leads with a specific verb and object: 'Approve or decline a pending booking request of the current team.' It clearly distinguishes the core review decision from generic status updates, and the outcomes for each decision are explicitly stated.

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

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

The description gives strong usage context: it only applies to pending bookings, past-time meetings can only be declined, and only the team owner/admin/lead owner may review. It does not explicitly name alternative sibling tools like update_booking_status, so it stops short of a full when-to-use-versus-alternatives statement.

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

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

Annotations already indicate destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond that: it discloses that the dimension list is replaced while overallAnalysis is preserved, that dimensions referenced by question dimensionScores or report.formula cannot be removed, and that code stability is maintained for dimensions with the same name. There is no contradiction; the description enhances the annotation. It clearly warns about irreversible replacement and scene-specific behavior.

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

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

The description is dense and long, but every sentence contributes essential context. It is front-loaded with the core action and then layers scene-specific rules and constraints. While it is a single block of text rather than bullet points, it is structurally logical and not redundant. It could be slightly more concise, but the content justifies the length.

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

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

Given the complexity of the tool (scene-specific dimensions, code stability, reference constraints, clearing behavior), the description is comprehensive. It covers prerequisites, limitations (random_knowledge_quiz unsupported), and interaction rules (e.g., formula cannot reference other dimensions). Since an output schema exists, return values are not needed. Nothing essential is missing.

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

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

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

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

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

The description states a specific verb and resource: 'Set the multi-dimension analysis (form.report.dimensionAnalysis) of a form, replacing the dimension list without touching overallAnalysis'. It clearly distinguishes from sibling tools like update_form_settings by focusing on the dimensionAnalysis attribute, and even names the prerequisite get_form call. This is unambiguous and purpose-specific.

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

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

The description gives explicit when-to-use guidance: it differentiates the knowledge_quiz scene (requires fieldCodes) from the scored_quiz scene (formula optional), and warns that 'Not supported for random_knowledge_quiz forms'. It also states prerequisites ('Call get_form first to read the question and dimension codes') and provides a clear way to clear the analysis ('Pass an empty dimensions array'). This leaves no ambiguity about when to invoke this tool versus alternatives.

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

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

Annotations already flag destructive=true. Description adds concrete destructive semantics: replace overwrites the entire tag set, add/remove are selective, remove tolerates stale codes, and changes are recorded on each lead's timeline. This is valuable context beyond the annotations.

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

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

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

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

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

Covers scope, batching limits, mode semantics, references the correct source of tag codes, and notes side effects (timeline). Nothing an agent needs to safely invoke it is missing.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Two tightly written sentences convey operation, persistence, and a prerequisite with no filler. Key facts are front-loaded.

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

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

For a simple single-parameter state-change tool with an output schema and full schema coverage, the description is nearly complete. It could mention that get_active_tenant reveals the current team, but that omission is minor.

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

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

The schema already fully describes tenantId with 100% coverage and even points to list_my_tenants for discovery. The description adds no new parameter meaning, so the baseline 3 applies.

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

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

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

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

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

The description conveys when to use it (change active team) and includes the membership prerequisite. It does not explicitly mention siblings or exclusion criteria, but the context is sufficiently clear among the listed tools.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

It gives explicit applicability conditions ('Only works on a booking whose status is scheduled; completed / no_show additionally require the meeting to have already started') and a pointer to the correct alternative ('To handle a pending request use review_booking instead'). This is textbook when/when-not guidance.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations only declare the generic destructive/openWorld/readOnly profile; the description adds the operationally critical merge semantics (report/openGraph merge by sub-key, systemText replaced wholesale, '' clears a sub-key, outcomes matched by code so existing images survive) and the rejection rules (removing an outcome referenced by question votes). It also clarifies that landingImage only sets the image and does not toggle the landing page.

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

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

Front-loaded with the field inventory, then the merge/clear rules, then the sibling routing — a sensible order with no filler sentences. It is dense and long, with some restatement of schema-level detail, but each clause carries a rule an agent needs.

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

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

All 11 parameters are accounted for, nested objects (report, openGraph, systemText) are explained at the merge level, and an output schema exists so return values need no prose. The description plus schema gives an agent everything needed to invoke this destructive update 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 3, but the description goes beyond the schema by defining cross-parameter behavior the schema cannot express: which sub-keys merge vs replace, the '' clear convention, and the accepted image sources (media id from finalize_image_upload, media URL, or '').

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

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

Opens with a specific verb+resource ('Update a form of the current team') and immediately enumerates the mutable fields, so the agent knows exactly what surface this tool owns. It actively carves itself apart from siblings by stating that questions go through add_question/update_question/delete_question/move_question and dimensionAnalysis through set_dimension_analysis.

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

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

Gives explicit when-not conditions: language 'is changeable only while the form has no language versions', scene 'never', and field-level routing to the question and dimension tools. It does not, however, distinguish itself from the sibling update_form_settings, which an agent could plausibly confuse with this tool.

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