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

Goes well beyond the annotations by disclosing what is cloned (structure, scoring/report config, visual settings, language versions) and what is deliberately dropped (redirect-after-submit, CTA URLs switched off). It also flags non-idempotency and the timeout/duplicate hazard, which the readOnlyHint=false/destructiveHint=false pair does not convey. Minor gap: no mention of auth/permission requirements or where the new form lands beyond 'current team'.

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

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

Front-loaded with the core action, then consequences, then caveats; each sentence carries information. Slightly dense in the middle (the CTA/link detail) but nothing is padding, and the non-idempotency warning is correctly placed last.

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

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

Output schema exists so return values need no explanation, only two simple params, and the description still covers cloning scope, dropped links, follow-up editing, and retry safety. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the provenance of templateId (find it with list_templates) and restates the title override in operational terms ('Pass title to override the template title'). That is small but real added 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 ('Create a new form in the current team from a public template') and immediately names the input source, distinguishing it from create_form and list_templates by name.

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 routing: use list_templates to find ids, prefer this over create_form when a suitable template exists, and follow up with update_form / update_question. It also gives a when-not-to-blindly-retry rule, which is genuine usage guidance.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The 'single item by code' framing implies it is not the whole-form delete and not a modification, but no sibling is named and no explicit when/when-not guidance is given. The ai_quiz note hints at a conditional context but is framed as a behavior, not a usage rule.

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

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

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

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

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

Three tight sentences: what it does, what it excludes, and how to handle failure. Scope and exclusions are front-loaded, and the retry caveat is placed last where it belongs. No filler.

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

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

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

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

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

Schema coverage is 100%, and the schema itself documents newTitle's default and sourceFormId's UUID type, so the baseline is 3. The description adds conceptual context (the copy is owned by you with fresh share links) but does not elaborate on either parameter beyond what the schema states.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare this as a read-only, non-destructive, closed-world operation, so the description does not need to restate safety. It adds useful behavioral context by stating that the result includes fields[] and report configuration, that outcome codes live at report.outcomeAnalysis.outcomes, and that translationLanguages lists non-primary versions. It does not address missing-form behavior or permissions beyond 'current team.'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The annotations already cover the safety profile (readOnly, non-destructive, non-open-world), and the description adds substantive behavioral detail beyond them. It discloses two non-obvious caveats: that `days` affects only the daily trend while all other blocks count all-time submissions, and that answer distributions cover only the first 10 SingleCheck/DropDown/Rate/TrueFalse questions with MultiCheck excluded. That materially changes how an agent interprets the results.

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 output blocks are front-loaded and each clause carries real information, with the caveats grouped after the enumeration and the use case placed last. The middle becomes a dense comma-separated list, but no sentence is wasteful.

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

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

Given an available output schema, the description need not spell out return values, yet it still summarizes them well enough for selection. All the behavioral surprises an agent needs to call and interpret this tool correctly are present.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description's note that `days` does not filter other blocks largely echoes the schema's own text. It reinforces rather than adds new meaning, so the baseline holds.

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 gives a precise verb+resource ('Read submission statistics for a form in the current team') and then enumerates the exact blocks returned (KPI overview, daily trend, channels, UTM combos, login types, device breakdown, per-question distributions). That is far more specific than the title. It stops short of naming the related sibling such as get_form_funnel, so the agent gets no explicit differentiation among analytics 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?

It supplies one clear usage context ('gauge how a quiz is performing and to suggest improvements'), which is implied guidance rather than explicit routing. It never says when not to use it or how it differs from get_form_funnel or get_form, leaving the agent to infer which analytics endpoint answers a given question.

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 only declare it as a safe, closed-world read; the description goes well beyond that by disclosing that internal diagnostics are omitted and that quoted contacts plus any email/phone embedded in answers are masked, while answers are otherwise verbatim. These are non-obvious output-shaping behaviors an agent could not infer from readOnlyHint/destructiveHint and that affect how it should interpret results.

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, with no filler or restatement of the name/title. The second sentence is dense with nested parentheticals and an exception clause ("except that any email address or phone number..."), which is informative but slightly harder to parse than the 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?

An output schema exists, so return-value explanation is not strictly required, yet the description still tells the agent what sections come back (overall / dimensions / outcome / AI report / AI evaluation) and which fields are suppressed or masked. For a single-parameter, read-only tool at full schema coverage, nothing an agent needs to invoke and interpret 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 the single parameter's schema text ("The record id (the `id` returned by list_records)") is essentially repeated in the description, so little meaning is added. The only marginal addition is the "in the current team" scoping hint, which implies ids are team-scoped and therefore only valid under the active tenant.

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 ("View the full detail of one submission record (lead)") and scopes it ("in the current team by its record id"). It also disambiguates from the listing sibling by pointing at the `id` field returned by list_records, and it enumerates the payload (examinee, answers, UTM metadata, report result), so an agent can tell it apart from get_lead, get_examinee, or list_records 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?

The prerequisite for calling it is explicit: the recordId must be the `id` from list_records, which establishes the intended workflow. There is no explicit exclusion clause naming when to prefer get_lead/get_examinee instead, so it is clear context rather than full when/when-not guidance.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With an output schema, full parameter descriptions and annotations available, the description supplies the parts structured data cannot: data provenance, sync direction, and result masking. The remaining gap is minor – page/limit behavior is left entirely to the schema.

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral detail: results are ordered reverse-chronologically by creation and omit question content, which agents cannot infer from the schema. Pagination behavior is left to the schema's limit field.

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

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

Two sentences, zero waste, with the resource scope front-loaded and the ordering/content caveat immediately after. The sibling pointer is placed last, where the agent needs it.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Beyond the readOnlyHint/destructiveHint annotations, it discloses non-obvious behavior: default ordering (newest first), field masking of emails and phone numbers written into answers, and the requirement to reference respondents by examineeId rather than masked email. That masking rule is exactly the kind of trap an agent needs warned about. It does not discuss pagination totals or rate/size limits, keeping it 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?

Three tightly packed sentences, front-loaded with what the tool returns, followed by filtering and the sibling pointer. Every clause carries information, though the parenthetical field enumeration is dense enough to slow reading slightly.

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 six-parameter, zero-required read tool with an output schema, the description covers return contents, ordering, filters, and the masking/ID caveats an agent must respect. The only missing piece is pagination/limit behavior, which the schema already annotates adequately.

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 six parameters are already documented, and the description only restates the filter axes (form, report status, submitted-at range) without adding format or edge-case guidance. Pagination parameters are not mentioned at all. Baseline 3 is appropriate when the schema carries the semantics.

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

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

States a specific verb and resource ('List submission records (leads) of the current team, newest first') plus the exact shape of each item (examinee, answers, UTM, compact report result). It also names the sibling it is not ('Use get_record for one record's full detail'), so an agent can discriminate 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?

Clear context for the summary-list use case and an explicit alternative route to get_record for full detail. There is no explicit exclusion, and the description loosely equates 'records' with 'leads' while a sibling list_leads exists, which leaves some ambiguity about which list tool to pick when the user says 'leads'.

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

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

Annotations already declare readOnly and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: results are limited to *active* templates in a *public* library and are ordered most-used first, neither of which appears in the schema or annotations.

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

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

Three front-loaded sentences that each carry useful information: scope and fields, filtering guidance, and the recommended next step. The parenthetical field enumeration is long but earns its place by summarizing the result shape.

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, yet the description still orients the agent well for a six-parameter list tool. Minor gap: it does not say where categoryId values come from, which an agent would need for that filter.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond it by explaining the cross-scene semantics of useCase with a concrete example ("personality" also returns scored_quiz personality tests), which is not derivable from the enum list alone.

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

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

States a specific verb and resource (list active templates in the public template library) plus the returned fields and the ordering (most-used first). This is clearly distinct from siblings like list_forms or list_records, which operate on tenant-owned data rather than a public library.

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 says to use useCase filtering to find templates for a goal across scenes, and names the follow-on call (create_form_from_template with the returned id) as the fastest way to build a quiz when a suitable template exists. The exclusion case — what to do when no suitable template exists — is only implied.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The annotations already mark the tool as destructive and open-world, but the description adds high-value semantics: report and openGraph sub-key merging, systemText wholesale replacement, empty-string clearing, outcome matching by code, and rejection when an outcome is still referenced. These details go well beyond the annotations and are consistent with 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 field list is front-loaded, and the remaining sentences focus on the highest-risk update semantics. For an 11-parameter nested mutation tool, the description is dense but appropriately sized with little wasted wording.

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 definition gives the agent enough context to call a complex nested update correctly: it covers merge-vs-replace behavior, clearing, code references, validation rejections, language constraints, and sibling routing. Return-value details are appropriately left to the output schema.

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

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

Even with 100% schema coverage, the description adds meaning that the schema fields alone do not fully convey: flagImg vs landingImage behavior, media ID/URL/clear semantics, report and openGraph merge rules, systemText clearing, and the language-change restriction. This materially reduces the chance of destructive or malformed updates.

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, then enumerates the exact form fields it updates. It clearly distinguishes question-level edits and standalone dimensionAnalysis edits by naming the sibling tools that handle them.

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

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

Explicitly routes questions to add_question / update_question / delete_question / move_question and standalone dimensionAnalysis to set_dimension_analysis. It also states when language can be changed, but does not explicitly contrast with update_form_settings for settings-oriented edits, leaving one sibling-routing gap.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is known; the description adds genuinely new behavioral rules the annotations cannot carry — merge-by-omission semantics, the code-existence validation on fields[], and that isActive=false pauses only this language version. It doesn't warn about wholesale replacement of the feedback block or other overwrite hazards, which would have earned a 5 for a destructive tool.

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

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

Three front-loaded sentences with no filler; the merge rule comes before the validation caveat and the isActive note last. The slash-separated parameter list in sentence two is a bit cramped but earns its space by orienting the agent across 10 parameters.

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

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

With a rich schema, full annotations, and an output schema, most of the burden is already carried elsewhere, and the description covers the important merge/validation semantics. The notable gap is lifecycle: nothing says whether the language version must pre-exist or how this interacts with create_form_translation, which an agent needs before a destructive save.

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 nested property docs already explain fields, report, booking, feedback and systemText in detail. The description's parameter value is the top-level mental model — same-shape-as-get_form_translation plus the omit-to-keep rule — which the schema repeats in several places rather than adds to. Baseline 3 is appropriate when the schema does this much of 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?

The description opens with a specific verb+resource+scope: "Save translated copy for one language version of a form," which separates it cleanly from update_form (whole form) and from list/get siblings. It stops short of naming create_form_translation or delete_form_translation as the alternatives, so the routing to siblings is implied rather than 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?

It tells the agent the working mode precisely: mirror the shape returned by get_form_translation, edit text in place, omitted fields keep their current value, and partial translation is allowed. What is missing is an explicit when-not — e.g. that a language version must already exist (or be created via create_form_translation) before this 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?

Discloses a non-obvious side effect: the change is recorded on the lead's timeline. The annotations only indicate non-read-only behavior, so the description adds useful behavioral context beyond what annotations 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?

Two sentences, front-loaded with the action and example. The mention of 'tag codes' is slightly tangential for a status-only tool, which prevents a perfect score.

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

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

For a simple two-parameter mutation with an output schema, this is complete: it states scope, the required lookup call, and the timeline side effect. No essential invocation information is missing.

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

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

The schema already covers 100% of parameters, including leadId provenance and that status must be a code from list_lead_settings.statuses[].code. The description reinforces the 'never guess' rule but adds little meaning beyond the schema.

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

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

Uses a specific verb ('move') plus a clear resource ('one lead of the current team') and outcome ('another follow-up status'), with a concrete example (new → contacted). This distinguishes it from other update tools by scope and entity.

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

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

Gives a concrete prerequisite: call list_lead_settings first to get valid status codes and never guess. It implies the intended use case clearly, but does not explicitly exclude or route to sibling alternatives like set_lead_tags or assign_leads.

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