RooQuiz

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

The annotations only say readOnlyHint=false and destructiveHint=false, which is minimal. The description adds valuable behavioral context: notes are visible to team members only, never to the respondent, max length is 2000 characters, and the operation is not idempotent — a timeout may still mean success, so blind retries can create duplicates. This goes well beyond the annotations.

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

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

The description is efficiently structured: purpose and visibility first, then constraint, optional parameter context, read alternative, and idempotency warning. Every sentence adds information and no space 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 write tool with an output schema, the description covers all necessary context: what the operation does, visibility rules, constraints, how to read existing notes, and the retry hazard. The agent has enough information to correctly invoke the tool and handle unusual outcomes.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra nuance by explaining that recordId is optional 'context' about the submission, which clarifies its role more practically than the schema's phrasing. It also reinforces the body length limit in line with the schema's maxLength.

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 action ('Write an internal follow-up note on a lead') and the resource ('lead of the current team'), while distinguishing it from sibling tools like update_lead or add_question by specifying it is an internal, team-only comment. The purpose is immediately evident 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 explicitly states when to use the tool and points to an alternative for related behavior: 'Read existing notes with get_lead(includeComments: true).' It also gives important retry guidance by warning about the non-idempotent timeout behavior and how to handle it, leaving no ambiguity about when or how to retry.

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 say only that the tool is not read-only and not destructive, so the description carries the full burden — and it delivers. The non-idempotency warning ('if the call times out it may still have succeeded... retrying blindly can create a duplicate') is exactly the behavioral disclosure an agent cannot infer. It also clarifies ignore-vs-reject semantics ('other fields are ignored', 'rejected for other question types'), preventing misuse.

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 first sentence names the core operation, and the long body earns its length because the tool genuinely spans 14 enum values and three scoring scenes. The nested parentheticals ('scored via correctAnswer, an unscored data-collection field in scored_quiz') reduce scanability, so a structured per-type summary would be clearer — but nothing in the prose 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 28-parameter tool with nested objects and complex scene/type interactions, the description plus the schema's own field-applicability summary cover every call-shaping decision: per-type required fields, scene restrictions, rejection behavior, and retry safety. An output schema exists, so return-value documentation is appropriately left out of the description's job.

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

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

Schema coverage is 100%, so the schema already documents every one of the 28 parameters, but the description adds cross-field semantics the schema cannot: which fields to omit per type, the correctAnswer-shape dependency on `multiple`, and the scene-level interplay (e.g., 'the submitted number feeds report formulas' for NumberField). This meaningfully raises the value above the baseline 3 that full schema coverage alone earns.

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 plus resource — 'Append an item to the end of a form' — and pins the position ('end'), which sets it apart from the sibling insert_question without needing to name it. The body then enumerates the 14 item types and contrasts them with display-only blocks, so an agent knows exactly what this tool creates versus create_form.

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

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

Gives strong situational guidance: prefer DropDown over SingleCheck/MultiCheck past 20 choices, maps each question type and field to its scene (quiz / scored_quiz / outcome_quiz), and routes random_knowledge_quiz bank setup to the web app as an explicit exclusion. It does not name sibling insertion/update tools as alternatives, so the append-vs-insert contrast is implied rather than stated — the only gap from a 5.

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

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

Beyond the annotations, it discloses notable side effects: 'me' or null to unassign, timeline recording for each change, and one aggregated notification for the whole batch. It also sets the member eligibility constraint, which is behavioral context the annotations don't convey.

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

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

The description is front-loaded with the core action and then packs behavioral details into a compact statement. It's slightly longer than necessary but every sentence adds distinct value, with no redundancy or filler.

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

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

With a complete schema, annotations consistently marking mutation/non-destruction, and an output schema present, the description supplies the remaining essential context: batching limits, assignee viability requirement, and side effects. It gives an agent enough information to call the tool correctly in one pass.

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

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

The input schema already provides 100% coverage for both parameters, including max 50 and 'me' semantics. The description adds extra meaning by clarifying that omitting or passing null unassigns, and by explaining the batching constraint directly in the tool's workflow rather than only in the schema.

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

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

The description states a specific verb ('assign') and resource ('leads') and clarifies the dual behavior: assign to a member or clear the assignee. It clearly distinguishes from siblings like update_lead by focusing on the assignment operation and batching rules.

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 actionable usage guidance: pass all lead ids in a single call up to 50, don't loop per lead, and the assignee must be an active non-viewer member. It references list_lead_settings for valid assignees, though it doesn't explicitly mention alternative tools or 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 cover readOnlyHint=false and destructiveHint=false; the description adds crucial behavioral context beyond them: creates primary language only, is not idempotent, timeout may still mean success, and retrying blindly can create duplicates. It also discloses that structuredContent.fields carries question codes and that the user must read them first before filling formulas. This is substantial behavioral disclosure.

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

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

The description is information-dense but not bloated. It front-loads the key purpose and workflow before diving into scene-specific details, and every sentence carries meaningful guidance. It could arguably be slightly shorter, but the density is justified given the tool's complexity.

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

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

Given the tool's very high complexity (nested report and question schemas, three scenes, multiple scoring modes) and the fact that an output schema exists, the description covers the essential workflow seams: what must be provided at create time, what must be deferred to update calls, the idempotency warning, and the language restriction. Nothing an agent needs to decide between creating vs. updating is left ambiguous.

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

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

Schema description coverage is 100%, so the baseline is 3; the description elevates this by providing cross-parameter workflow semantics (e.g., the relationships between questions codes, report.formula, dimensionAnalysis, and the returned structuredContent). It explains creation-time dependencies that the schema's individual field descriptions cannot express, though much of the parameter meaning is already in the schema.

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

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

The description opens with a specific verb and resource ('Create a form in the team this token is bound to') and immediately differentiates itself from sibling tools by noting it passes questions and report configuration in one call rather than per-question follow-ups. It clearly distinguishes the create operation from update_form, set_dimension_analysis, and create_form_translation, which are named explicitly.

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

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

The description explicitly states when to use create_form vs. update_form / set_dimension_analysis (fill in formula and dimensionAnalysis afterwards) and vs. create_form_translation (primary language only, add other languages separately). It also gives precise scene-specific guidance (outcome_quiz requires report.outcomes at create time; scored_quiz dimensions must be defined in the same call).

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

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

The description goes far beyond annotations by disclosing that the call clones structure, scoring/report configuration, visual settings, and all language versions in one call. It also surfaces the critical non-idempotency behavior: timeouts may have succeeded, so blind retries can create duplicates. This is exactly the kind of behavioral nuance an agent needs.

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

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

The description is dense but every sentence contributes: what it does, what it copies, how to override the title, where to find template IDs, when to prefer it, and the duplicate-risk caveat. It is front-loaded with the core action and includes 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 two-parameter creation tool with an output schema, the description covers the essential context: source of IDs, scope of cloning, post-creation workflow, alternatives, and unique failure behavior. The non-idempotency warning addresses the most important edge case an agent could encounter.

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

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

Schema coverage is already 100%, so the schema documents both parameters. The description adds practical meaning by explaining how to discover a templateId via list_templates and how title overrides the template title. This supplements the schema without repeating it.

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

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

The description states a specific verb and resource: 'Create a new form in the current team from a public template.' It further distinguishes this tool from sibling create_form by positioning it as the template-based path, and points to list_templates for ID lookup. This is unambiguous and well-separated from related tools.

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

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

The description gives explicit when-to-use guidance: prefer this when a suitable template exists, versus building from scratch with create_form. It also references list_templates for finding template IDs and mentions post-creation adjustment via update_form / update_question. This effectively routes the agent to the correct tool among many siblings.

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

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

Beyond the annotations, it discloses key behaviors: the source text is cloned into the new version, the result is returned for immediate translation, and code fields must stay identical to the source. This gives the agent a clear model of what happens on invocation.

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

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

The description is compact and front-loaded: the main action and outcome are in the first sentence, followed by essential workflow constraints in the second. No filler or redundant restatement.

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

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

The description covers the purpose, constraints, next steps, and relationship to sibling tools. With an output schema present and annotations providing safety cues, nothing critical is missing for an agent to invoke this tool correctly.

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

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

The input schema already documents both formId and language with 100% coverage. The description adds contextual meaning (language must differ, translation is per-language) but does not introduce new parameter details beyond the schema.

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

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

The description clearly states the action: add a language version (translation) to a form. It also distinguishes itself from related siblings like update_form_translation and list_form_translations by explaining the cloning and post-save workflow.

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

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

It gives explicit context: language must differ from primary, at most one translation per language, and the workflow of editing then calling update_form_translation. It also points to list_form_translations for checking existing translations. It could be more explicit about when not to use this tool, but the constraints strongly imply that.

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 indicate destructive behavior, but the description adds substantial context beyond that: soft delete semantics, 5-day recoverable window, auto-purge behavior, and that submission records are preserved until permanent purge. 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?

Three sentences with the core action front-loaded, followed by recovery, permissions, and data-retention details. Every sentence contributes meaningful information without redundancy.

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

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

For a one-parameter soft-delete tool, the description covers the essential context: what happens to the form, how long it remains recoverable, how to restore it, who has permission, and what happens to submissions. The output schema and annotations cover the rest.

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

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

Schema description coverage is 100% and the single parameter formId is already described as 'The form UUID to move to trash.' The description adds the 'current team' scope but otherwise relies on the schema, which is acceptable at the baseline for full coverage.

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

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

The description states a precise verb and resource: 'Move a form into the trash (soft delete) in the current team.' It clearly differentiates from siblings like restore_form and delete_form_translation by naming the exact operation and scope.

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

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

Explicitly says when to use restore_form as the recovery alternative, notes that the form is hidden from list_forms after deletion, and states the permission requirement (form owner or team owner/admin). This gives clear guidance on when and by whom the tool can be used.

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

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

Even though the destructiveHint annotation already marks this as a destructive operation, the description goes further by stating that submission records are anchored to the source form, are not deleted, and that historical reports fall back to the source text. This is exactly the kind of behavioral consequence an agent needs before calling a delete 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?

Three sentences no unnecessary words. The main action appears immediately, followed by the two most important side-effect insights, then a constraint. Everything is structured for fast parsing 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?

The description covers the purpose, the exact scope (per-language translation), the side-effect safety guarantee (submissions not deleted), the report fallback behavior, and the primary-language restriction. With the input schema and output schema present, nothing relevant to correct invocation is missing.

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

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

The schema covers both parameters with 100% coverage, so a baseline of 3 is appropriate. The description adds additional meaning by clarifying that the 'language' parameter must be a non-primary translation language, which is important selection guidance beyond the bare enum 'Which language version to delete.'

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

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

The description opens with a precise action-verb and resource: 'Delete one language version (translation) of a form.' That clearly identifies what the tool does and naturally sets it apart from deleting an entire form. The final sentence reinforces the boundary by noting the primary language is not affected by this operation.

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

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

The description gives a clear intended use—deleting a translation language—and explicitly warns that the primary language cannot be removed through this tool. It does not name sibling alternatives like 'delete_form' when a full form deletion is intended, so a small routing gap remains.

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 destructiveHint=true, so the description's mention of 'delete' is consistent. The description adds valuable behavioral context beyond annotations: it explicitly states that deleting the last item is permitted (form can be empty), and clarifies that it handles non-question entities (page breaks, display blocks). This transparency about edge cases exceeds what annotations alone convey.

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

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

The description is two sentences, front-loaded with the core action and scope. It efficiently packs key information: the primary purpose, the range of deletable item types, and an important edge rule (deleting the last one). No redundant words or irrelevant details; every sentence earns its place.

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

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

For a simple delete operation with only two well-described parameters and an existing output schema, the description covers the essential behavioral gaps: what can be deleted and the rule about the last item. It would be improved by mentioning any side effects or cascading behavior, but for this tool's simplicity the coverage 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%, so both parameters (formId and code) are already documented. The description's phrase 'by code' reinforces the code parameter but adds no new semantics not present in the schema. With high coverage, a baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description states a precise verb ('Delete'), a specific resource ('a single item from a form'), and enumerates the allowed item types (question, page break, display block). It clearly separates this tool from delete_form and delete_form_translation by scoping to individual components. The addition of the 'last one is allowed' rule further clarifies the exact scope.

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

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

The description implies usage by specifying what it deletes, but it does not explicitly contrast with alternatives like delete_form or state when to choose this over other deletion tools. The context (sibling names) makes the distinction obvious, but the description itself lacks explicit when-to-use or when-not-to-use guidance.

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

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

The description goes far beyond the schema: it states exact cloned fields, what is deliberately excluded, that share links are regenerated, and that the operation is not idempotent after a timeout. This is especially important for a mutating tool with no annotations to disclose side effects.

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

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

The description is front-loaded, covers what, what-not, and how-to-avoid-duplication in four dense sentences. Every sentence adds meaningful value, and the non-idempotency warning is high-value rather than filler.

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

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

Given there is no output schema, the description thoroughly covers selection and side-effect safety. The only notable gap is that it does not explicitly state what the tool returns (such as the new form object/id), which would be helpful in a multi-step workflow.

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

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

The input schema already documents both parameters fully, including the default title for newTitle. The description adds no significant parameter-level meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource ('duplicate a form') and precisely enumerates what is and is not cloned, making its purpose unmistakable. It also distinguishes itself from related sibling tools by stating it creates a brand-new copy with fresh share links.

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 usage context: 'useful for cloning a proven quiz and tweaking it', and warns against relying on it for things like preserving submission records or sharing. It does not name a specific alternative tool to use instead, but the 'does not copy' list clearly communicates 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?

The description clearly discloses the state-changing effects: verifying the object, recording it in the team media library, and returning a media ID and public URL. This adds behavior beyond annotations. It also implicitly warns that the upload must exist for verification, though it does not fully describe error cases.

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 compact sentences capture the full workflow. The front-loaded 'Step 2 of 2' orients the user immediately, and every sentence in the description adds useful information with no redundancy.

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

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

The description covers the prerequisite sequence, the side effects, the return value, and downstream usage. With an output schema available and a complete parameter schema, nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds coordination semantics by noting that key, filename, mimeType are the values from prepare_image_upload, which is critical for correct invocation. Alt text is not described in the prose but is already explained in the schema.

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

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

The description states the specific verb 'finalize', positions it as 'Step 2 of 2' for adding an image, and clearly distinguishes it from prepare_image_upload. It says exactly what the tool does: verifies the upload, records it in the media library, and returns a media ID and public URL.

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?

Usage is explicit: call this AFTER the PUT request to the uploadUrl from prepare_image_upload. It also provides downstream guidance for using the returned media id with update_form for covers. This makes when-to-use vs. alternatives unmistakable.

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

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

Annotations already cover read-only behavior, so the description adds valuable context beyond them: it reveals the additional `examineeSignupDisabled` field and explains why it matters for quizzes requiring login. This is useful behavioral insight that an agent would otherwise not infer from the schema alone.

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

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

The description is slightly longer than the most minimal needed, but each clause carries meaning, including the nuanced exam-signup explanation. It is front-loaded with the core purpose and elaborates in a way that earns its 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?

With zero parameters and an output schema, the only important context an agent needs is what the active tenant means and how to interpret the notable field. The description covers the full usage scenario, including the 'nobody can submit' pitfall, making it complete for the tool's 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?

The tool has no parameters, so the description rightly spends no time on them. The baseline is 4 since there is no parameter semantics gap to compensate for; the description's focus on the return fields is the appropriate semantic equivalent.

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 specifies a clear verb ('Return') and resource ('team (tenant) this token is currently operating against') while also clarifying the relevant scope: active tenant, as opposed to a list of all tenants or switching. The added detail about write tools defaulting to this team further disambiguates this from sibling getters.

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

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

The description clearly tells when to check the active tenant ('Check it before blaming a quiz for "nobody can submit"') and explains the field's implications for signup behavior. It does not explicitly name alternatives or exclusion cases, but the intent is unambiguous given the context and sibling tools.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing behavioral nuances: returned availability is computed from weekly rules minus taken slots, enabled:false appears when booking is off or plan doesn't include it, the booking's own slot is excluded when rescheduling, and server-side clamping of the date range. This is detailed and non-obvious behavioral context.

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

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

Every sentence adds relevant information: core functionality, failure/disabled state, rescheduling behavior, required ordering, and clamping. It is front-loaded with the core action and flows naturally from general to specific, with no filler or repeated schema details.

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

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

The description covers the central behavior, edge cases (disabled/enabled:false), rescheduling nuances, server-side constraint, and relationship to required sibling call, leaving little to infer. The existence of an output schema reduces the need to explain return shape; the added context about the bookingId parameter and clamping is more than enough for an agent to select and invoke this tool correctly.

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

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

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description additionally enriches the meaning of bookingId by explaining its role in rescheduling and non-counted slots, and warns about server-side range clamping—but it does not substantially expand on fromDate/toDate beyond the schema's 'ISO datetime' and 'exclusive' scope.

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 ('Read'), a resource ('bookable time slots'), and the computation source ('weekly booking rules minus what is already taken'). It is clearly distinguished from sibling tools by its scope (availability vs. bookings/leads/forms), and the mention of reschedule_booking shows where 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?

The description provides explicit context for when to use the bookingId variant and the strong instruction to call this before reschedule_booking because out-of-range start times are rejected. It does not explicitly name alternatives to exclude or mention when to prefer list_bookings, but the usage context is clear and practically actionable.

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

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

The description discloses useful behavioral context beyond annotations: it says customData is included and that sensitive auth fields are never returned. These are meaningful runtime guarantees that help the agent interpret results and set 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?

The description is a single, well-structured sentence that front-loads the core action and resource, adds the key identifying constraint, and closes with the important security behavior. There is no wasted language.

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 this is a simple fetch-by-ID tool with only one required parameter, an output schema, and helpful annotations, the description is complete. It covers scope, identifier provenance, response contents, and the non-return of sensitive fields, so nothing essential is missing.

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

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

The schema already documents the parameter at 100% coverage, including the business ID example. The description reinforces that the ID is from list_examinees and gives an example, but adds little new semantic 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 states a specific verb ('View') and resource ('full detail of one examinee'), with a clear scope ('in the current team') and the exact identifier to use. It also distinguishes itself from list_examinees by clarifying it returns full detail rather than a summary list.

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

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

The description clearly implies when to use this tool: when a caller needs full examinee detail or customData rather than just the identifier list. It does not explicitly name alternatives or exclusions, but the contrast with list_examinees and the single-ID focus provide adequate usage context.

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

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

Annotations already mark this as read-only and non-destructive; the description adds value by revealing where outcome codes live and how language versions are represented. This is helpful context beyond the annotations, though it does not discuss errors or edge cases.

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

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

The description is compact, front-loaded, and every sentence carries meaningful scoping or nesting information. It is easy to scan and contains 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?

Given the read-only annotations, full schema coverage, and presence of an output schema, the description covers what an agent needs to invoke the tool successfully. It also provides helpful pointers into the response structure, though it could clarify the active-tenant context slightly more explicitly.

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

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

The input schema has 100% coverage and clearly documents id, includeFields, and includeReport with defaults. The description mentions fields[] and report configuration but does not add much parameter-specific guidance beyond what the schema already provides.

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

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

The description uses a specific verb ('View one form of the current team in full') and explicitly names the main contents: questions fields[] and the report configuration. This clearly distinguishes it from sibling tools like list_forms, get_form_translation, and get_form_funnel.

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 it — when a single form's full configuration is needed — but it does not explicitly contrast the tool with alternatives or provide when-not-to-use guidance. The 'current team' scope is useful, but the choice between this and related getters is left to the agent.

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, and the description adds behavioral context: the data source (form_sessions telemetry), scoping to the current team, the look-back window, and the specific funnel/drop-off reports returned. This goes beyond the annotations and clearly sets 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?

The description is detailed but not padded. It front-loads the core purpose and then enumerates the specific outputs. The funnel stage list and per-channel breakdowns are informative and earn their place, though the sentence is slightly long.

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, high schema parameter coverage, and safety annotations, the description is complete enough for an agent to select and invoke the tool correctly. It specifies scope, data source, output dimensions, and the intended use case.

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 formId and days including default and max/min. The description only reflects the 'last N days' notion without adding new meaning to parameters. This matches the baseline expected when schema carries the semantic load.

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 starts with a specific verb and resource: 'Read the conversion funnel for a form in the current team over the last N days'. It then enumerates the exact funnel stages and breakdowns, making it clearly distinct from generic siblings like get_form_stats or get_form.

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

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

The description gives a clear intended use: 'Use this to find where respondents drop and understand/improve conversion.' It implies this tool is for conversion analysis rather than general form reading or stats, but it doesn't explicitly exclude alternatives or mention when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that. It adds useful context: the tool reflects current team scope, reports whether the custom domain is actually serving, and indicates whether the form will accept responses. This goes beyond the structured annotations without contradicting them.

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

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

The description is dense but not bloated. It front-loads the main output and then lists use cases and the sibling alternative. Every clause contributes meaning, and it keeps the agent-oriented guidance in the final sentence.

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

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

The tool has an output schema, so return values are covered. The description explains the key context an orchestration agent needs: scope of current team, embed modes, custom domain serving status, and delivery-settings sanity checks. Combined with the rich annotations and complete param schema, nothing critical is missing.

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

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

Schema coverage is 100%, so the parameter descriptions already carry the load. The description adds value by explaining utmSource's purpose: 'Pass utmSource to get every link and snippet tagged for one channel.' It does not repeat every schema-field detail, which is appropriate given high schema coverage.

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

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

The description clearly identifies the tool as a get for form sharing information: public answer links, custom domain serving status, embed snippets in three modes, and delivery settings. It uses a specific verb/resource combination and differentiates itself from siblings by explicitly pointing to update_form_settings for changing switches.

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

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

It gives explicit use cases: 'Use this to answer "give me the link / the embed code" and to sanity-check a launch; change the switches with update_form_settings.' This tells an agent when to use this tool and when to prefer the sibling instead.

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

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

The annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by specifying the scope ('current team', 'last N days') and the precise breadth of what is returned, which goes beyond the raw schema annotations.

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

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

The description is front-loaded with the verb, resource, time scope, and team scope, then lists the returned statistical categories. It is a long single sentence, but each part is useful and not redundant.

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 returns a rich set of analytics, and the description covers the operation, scope, time window, and the actual data product, while the output schema handles formal return details. Nothing important needed to call or interpret the tool correctly appears to be missing.

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

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

Parameter schema coverage is 100%, with both formId and days documented. The description adds little semantic detail beyond calling days 'last N days', which aligns with the schema, so the baseline of 3 applies.

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

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

The description opens with a concrete, non-generic operation: 'Read submission statistics for a form in the current team over the last N days', then enumerates the specific report components it returns. It clearly distinguishes this tool from sibling operations like get_form_funnel or list_records, which serve different purposes.

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

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

The description gives a clear intended use: 'Use this to gauge how a quiz is performing and to suggest improvements.' However, it does not explicitly contrast with alternatives like get_form_funnel or get_form, so it lacks explicit when-not-to-use 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by explaining the failure case when a language version does not exist yet and by clarifying that the returned content includes mirrored fields[] and a report.

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

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

Three sentences, each serving a clear purpose: what the tool reads, how to use it in the edit/save workflow, and when it errors. The main purpose is front-loaded and there is no filler or redundancy.

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

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

For a simple read operation with two fully documented parameters, a schema, and read-only annotations, the description covers the main function, the mutation workflow it supports, and the error condition. Nothing needed for a correct call is missing.

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

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

The schema documentation covers both parameters completely the formId and language enum, so the baseline is at 3. The description reinforces the language parameter's meaning by calling it a 'language version (translation)', which is consistent with the schema but adds minimal extra semantic detail.

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

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

The description starts with a specific verb and resource: 'Read the full content of one language version (translation) of a form', and additionally highlights the mirrored fields[] and report. It also references the relevant sibling operations (update_form_translation, create_form_translation), so an agent can tell it apart 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?

It gives explicit workflow guidance: use this tool to fetch the current draft before editing, keep codes identical to the source form, then save with update_form_translation. It also states when the call fails and directs the agent to create the translation first with create_form_translation.

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?

With readOnlyHint=true and destructiveHint=false, the annotations already establish that this is a safe read operation. The description adds useful behavioral context by specifying current-team scope, optional data inclusions, and the leadId/examineeId reference rule. It does not need to explain return format since an output schema is present.

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 focused sentences with no filler. The primary purpose is front-loaded, followed by optional include behavior and a defensible reference rule. Every sentence contributes useful 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 required leadId, optional boolean parameters, read-only annotations, and existing output schema, the description is sufficiently complete for an agent to select and invoke the tool correctly. It covers scope, optional behavior, and a critical lookup guardrail without leaving any obvious missing context.

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 leadId and the three inclusion flags. The description adds context around those flags and reinforces the leadId naming convention, but it does not provide significantly more parameter-level meaning than the input schema itself.

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

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

The description clearly identifies the action ('view one lead') and the resource ('by leadId'), and it enumerates the specific data returned: follow-up status, assignee, colour tags, respondent block, and next upcoming booking. It does not explicitly name sibling tools like get_examinee or list_leads, so sibling differentiation is implicit rather than 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?

The description gives a clear usage context: retrieving a single lead of the current team by leadId, with control over optional inclusions such as submission history, comments, and activity timeline. It also offers the practical guardrail that respondents are referenced by examineeId and never by masked email. It stops short of 5 because it does not explicitly list alternatives or state when not to use this tool.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false, so this is clearly a safe read operation. The description adds useful behavioral nuance beyond those hints: the report result is 'frozen', and email addresses or phone numbers in answers are masked on return. This gives the agent realistic expectations about data fidelity without needing to call the 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?

Two sentences, front-loaded with the primary purpose and resource, followed by a useful enumeration of contents and the key masking behavior. Every clause contributes actionable information, and there is no redundant filler.

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

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

Given a one-parameter schema, an existing output schema, and annotations covering safety, the description is complete. It explains how the id is obtained, scopes the record to the current team, lists the key subcomponents, and reveals the masking behavior an agent needs to set expectations before invoking.

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 fully documents recordId and even restates the provenance from list_records. The description largely repeats that same provenance. Since schema_description_coverage is 100%, the baseline is 3; the description does not add much parameter meaning beyond tying the operation to the current team.

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 the full detail of one submission record') and then enumerates the included contents: examinee, answers, UTM metadata, and the frozen report result. This scope is clear enough to distinguish get_record from list_records (one record vs. lists) and from get_form or get_lead, even without naming them as alternatives.

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

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

The description gives clear context: use this when you need the complete detail of a single record in the current team, and it explicitly ties the required parameter to the id returned by list_records. It does not name explicit alternatives or when-not-to-use conditions, so it stops short of a 5, but the usage context is unambiguous.

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

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

Annotations only say readOnlyHint=false, openWorldHint=false, destructiveHint=false — they do not convey the critical non-idempotence behavior. The description adds substantial transparency: calls may succeed despite a timeout, blind retries can create duplicates, and the correct recovery procedure is to check first. It also discloses the anchor requirement (existing field code from get_form), which is behavioral context beyond the annotations.

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

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

The description is two dense sentences that front-load the core purpose and most important routing rule, then add the idempotence warning. Every clause earns its place — there is no filler, no restatement of schema content, and the critical operational warning is placed at the end where it completes the mental model rather than competing with the purpose statement.

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?

Despite having 30 parameters, a rich schema, nested objects, an output schema, and a field-applicability matrix in the input schema, the description still covers the key contextual points an agent needs to call it correctly: position anchors, end-insert routing, and non-idempotence recovery. It does not enumerate every type-field combination, but the schema already carries that burden; the description correctly focuses on the decision-level context that the schema does not convey.

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 itself documents every parameter, setting a baseline of 3. The description adds value above that baseline by naming the two anchor parameters (before/after) up front, referencing get_form's field.code as the source, and establishing add_question as the endpoint alternative. The semantic distinction between before/after and end-insert is positioned in the description text, not just in the schema.

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

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

The description opens with a specific verb and resource ('Insert an item at a specific position') and enumerates the insertable item kinds (question, page break Breaker, display block Statement/Swiper). It distinguishes itself from add_question (append at end) and references get_form's field.code as the anchor mechanism, which clearly separates it from siblings like update_question or move_question.

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

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

The description explicitly states when to use before/after anchors, how to insert at the very front, and that insert-at-end should go to add_question. The not-idempotent warning with a check-then-retry strategy gives concrete operation guidance. This is explicit usage direction that an agent can act on without inference.

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

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

Annotations indicate this is a write operation but the description goes further by disclosing that an email is sent, that a join link is returned, and that the call is rejected for non-admin roles. It also clarifies active-tenant scoping and specific failure modes, adding substantial context beyond the annotations.

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

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

The description is front-loaded with the core action and then layers permission, role defaults, failure conditions, and tenant-scoping guidance. Every sentence carries distinct operational value, and nothing is redundant.

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

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

The description covers the essential context: target scope, required permissions, role constraints, side effects, return value, and common failure cases. An output schema exists, so return-value details need not be fully spelled 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?

Schema coverage is 100% and the schema already documents both parameters, including the role enum semantics and default. The description repeats much of this information rather than adding new parameter-level meaning, so the baseline of 3 is appropriate even though the tool context is rich.

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

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

The description states a specific verb and resource: invite someone to the active team by email. It also names the key outcome, sending an invitation and returning a join link, which distinguishes it from unrelated sibling tools. No ambiguity remains about what operation the tool performs.

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

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

The description explicitly states the permission model, role defaults, and failure conditions, and it tells the caller to use list_my_tenants/switch_active_tenant if a different team should be targeted. This provides clear when-to-use and how-to-prepare guidance.

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

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

Annotations already mark this tool as read-only and non-destructive, and the description adds meaningful behavioral context beyond that: bookings are scoped to the current team, sorted earliest first, tied to a lead owner and source quiz, and attendee names/emails come back masked. These details are not inferable from the annotations alone.

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

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

The description is compact and front-loaded with the core purpose, then adds distinct, practical details: item shape, filtering, a typical approval-queue workflow, and the masked attendee caveat. There is no filler or redundant 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?

For a read-only listing tool with 9 optional, well-documented parameters and an output schema, this description is complete enough for selecting and invoking the tool. It covers scope, ordering, item content, filtering behaviors, and a real workflow in several lines, so an agent can confidently decide when and how to call it correctly.

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

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

Schema description coverage is 100% and each parameter already has a clear description covering time range, status enum semantics, quiz, respondent, pagination, and sort. The tool description reinforces the filtering categories but does not add meaningful parameter-level details beyond what the schema already explains, so 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 starts with a specific verb, 'List', and a concrete resource: '1:1 bookings (discovery calls / consultations booked from a quiz report page) of the current team'. It clearly distinguishes this from sibling tools like get_booking_availability, reschedule_booking, and update_booking_status by stating exactly what resource and scope this operation is about.

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 usage context: read-only listing of the current team's 1:1 bookings, earliest first, with defined filters and a typical use case ('status pending lists the approval queue waiting on someone'). It does not explicitly name alternative sibling tools or say when not to use this tool, so it is slightly short of fully explicit 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?

Beyond the readOnlyHint and destructiveHint annotations, the description reveals important behavior: sensitive auth fields are never returned, the business ID is unmasked, and ordering is newest first. This is meaningful context the agent cannot infer from annotations or schema alone.

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

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

The description is compact and front-loaded: it states purpose and ordering first, then field-sensitive behavior, then routing guidance. Every sentence earns its place without repetition or filler.

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

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

Given the output schema exists, all parameters are documented, and annotations cover the safety profile, the description fills the remaining gaps: scope, ordering, sensitive-field filtering, and selection between siblings. Nothing needed for correct invocation is missing.

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

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

All three parameters (limit, search, status) are already fully described in the JSON schema, including defaults, enums, and constraints. The description adds no extra parameter-level guidance, 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 uses a specific verb (list), a clear resource (examinees/respondents), and states scope (current team) and ordering (newest first). It also distinguishes itself from get_examinee by explaining the difference in scope and detail.

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

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

The description explicitly states when to use get_examinee instead: when full detail including customData is needed. It also explains that examineeId is the value consumed by get_examinee / update_examinee, giving the agent a clear routing rule across siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: results are returned in reverse chronological creation order and omit question content. This helps the agent understand what the response will and will not contain without relying on assumptions.

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

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

The description is a single lean sentence that fronts the core purpose and immediately appends the most important caveat (no question content) with a pointer to get_form. Every phrase earns its place, there is no fluff, and the structure makes the primary action and the exception equally clear.

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

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

For a simple read-only list tool, the description covers the essential behavioral nuances: team scope, ordering, and exclusion of question content. The tool has an output schema, so return values don't need to be described, and annotations plus full parameter schema cover the rest. Nothing necessary for safe and correct invocation is missing.

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

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

Schema description coverage is 100%, and each parameter (limit, scene, titleContains) is documented with enough meaning in the schema itself. The description does not add extra parameter-level semantics, which is acceptable given the baseline of 3 when the schema fully covers the parameter detail.

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

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

Description states a specific verb ('List') and a clear resource ('forms of the current team'), and additionally distinguishes the listing behavior from detail retrieval by noting that question content is omitted and pointing to get_form for details. This makes the purpose immediately identifiable and differentiates it from sibling tools like create_form and delete_form.

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

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

The description provides clear usage context: list forms when you need an overview, and use get_form when you need question content or details. It gives explicit guidance on the alternative tool for a different need, though it does not mention other related tools like list_form_translations or list_templates, which would have made the routing even clearer.

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

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

Annotations already cover the safe read-only nature of the tool. The description adds valuable behavioral detail: the response includes language, isActive flag, public share links, and timestamps, and the primary language is deliberately not included. This is meaningful beyond what the annotations express.

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: the first states the operation, the second itemizes the returned data, and the third explains an important exclusion. There is no filler, and the most critical recognition comes immediately.

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

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

For a single-parameter read-only list operation with an existing output schema and annotations, the description is complete. It tells the agent what will be listed, what fields are returned, and what is deliberately absent, leaving no important detail missing for correct invocation.

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

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

The only parameter, formId, is fully described in the schema as 'The source form UUID', giving 100% schema description coverage. The description restates the form context but adds no extra semantic detail beyond the schema's own 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?

Description begins with 'List the existing language versions (translations) of a form', which is a specific verb and resource. It also distinguishes itself by noting the primary language lives on the form itself and pointing to get_form.language, so an agent can tell this tool apart from related get_form and get_form_translation tools.

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

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

The description clearly conveys the tool's purpose and explicitly excludes the primary language, directing the agent to get_form.language for that concern. However, it does not explicitly mention get_form_translation as the alternative for retrieving a single translation, leaving a small gap in alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond annotations and schema: aggregation semantics ("one lead per response across all forms", i.e., dedup does not include), default ordering ("newest activity first by default"), and masked email handling ("never by a masked email"). These are real behavioral traits an agent could not infer from the parameter 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?

Five sentences, each earning its place: purpose + aggregation semantics, default ordering, filter summary, code-domain management, and ID/masking convention. It is front-loaded with the core definition and does not repeat schema boilerplate.

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 10-parameter tool with an output schema, the description covers the decision-critical semantics: aggregation, default sorting, code validation, and masked-employee handling. Pagination bounds, the page-local filtering caveat, and the special assignee value "me" remain in the schema, which is acceptable. The complete is modest — it does not name sibling alternatives for raw-record or single-lead access — so very close to fully complete but not absolutely.

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

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

Schema description coverage is 100%, so the parameters are already fully documented and the baseline is 3. The description adds value on top by summarizing the filter dimensions in one line (status / assignee / tags / created-at range / keyword / upcoming booking) and by providing the identifier discipline (leadId vs examineeId, never a masked email) that the schema itself does not state. This moves it above baseline, though it still relies on the schema for precise meanings.

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 + resource + scope: "List the leads (CRM records) of the current team" and immediately disambiguates it from siblings with "one lead per respondent across all forms". It also lists what each lead carries (status, assignee, tags, next upcoming booking), so the agent can distinguish list_leads from list_records and list_examinees without opening their 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?

The description gives clear context: the tool targets the current team's aggregated CRM view, and it adds an explicit prerequisite — "call list_lead_settings first to get the valid ones, never guess." However, it does not explicitly name alternative tools to rule out (e.g., when to use list_records or get_lead instead), so the when-not-to guidance is 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 declare this read-only and non-destructive, so the safety profile is covered. The description adds useful behavioral context beyond the clues: the returned codes/ids are team-scoped and the write tools will reject unknown values, which explains the side-effect context of a read tool meant as a prerequisite. It does not describe errors or pagination, but those are irrelevant here.

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

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

Two sentences carry all needed information without any waste: the first lists the three concrete outputs, the second gives the essential call-before context and rationale. The most important information is front-loaded.

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

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

Given a zero-parameter input schema, a low-complexity read operation, and an existing output schema, the description is fully adequate. It explains what is returned, that data is team-specific, and how the result should be used before related write calls. Nothing necessary for an agent to invoke it correctly is missing.

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

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

The tool has 0 parameters and an empty input schema, so there is no parameter meaning for the description to add. Per the baseline for zero-parameter tools, this is complete enough without any parameter-specific descriptions.

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

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

The description opens with an explicit verb and resource ('Read the current team's lead configuration') and lists exactly what is returned: follow-up status codes with label/color/order, the color tag library, and assignable members. It also differentiates itself from the write-related siblings because it is positioned as the read-side lookup.

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: call it before update_lead / set_lead_tags / assign_leads. It explains why this ordering matters, since the values are team-specific and the write tools reject unknown values. This is strong routing context for an agent.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the result includes all user memberships and the isActive field indicates the token's current operating tenant. No contradictions 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 one efficient sentence with no fluff. The main action is front-loaded and the field clarification (isActive) is added in a compact clause, earning 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 is low-complexity (0 params), has an output schema, and annotations cover the safety profile. The description adequately explains what it lists and how to interpret the key field. 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?

With zero parameters, baseline is 4. There are no parameters to describe, and the schema has nothing to document, so this score is appropriate and the description need not compensate for anything.

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

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

The description uses a specific verb ('List') and clearly identifies the resource: all teams/tenants the current user belongs to. It also explains the isActive field, distinguishing it from get_active_tenant by noting all tenants are returned and the active one is marked.

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 usage—when you need the full list of tenants for the current user—but does not explicitly mention alternatives like get_active_tenant or switch_active_tenant, nor does it state when to prefer this tool over those. The mention of isActive provides indirect context but not explicit routing.

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

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

Beyond the readOnly/destructive annotations, it discloses meaningful behavioral traits: newest-first ordering, the compact report shape, team-level scoping, automatic masking of emails and phone numbers, and the instruction to reference respondents by examineeId because masks are not stable identifiers. This is genuinely useful context that the annotations alone do not provide.

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

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

The description is information-dense yet compact: one sentence for the core behavior, one for item shape, one for optional filters, and one safety/alternatives tip. Every sentence earns its place, and the most important information is at the front.

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 readOnly annotations, full input-schema coverage, and the presence of an output schema, this description leaves very little unresolved. It explains item contents, filtering, masking constraints, and routes to get_record, so an agent can confidently select and call the tool.

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

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

The schema already documents all 6 parameters with 100% coverage, so the baseline is 3. The description does add a concise grouping of the optional filters (form, report status, submitted-at range), but it mostly restates what the parameter descriptions already say rather than introducing new 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?

The description opens with a specific verb-resource combination: "List submission records (leads) of the current team, newest first." It enumerates what each item includes and explicitly distinguishes itself from get_record, making the tool's scope clear even among many list_* siblings.

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

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

The description gives clear context on optional filters and on how to reference respondents safely, and it explicitly points to get_record when full detail is needed. It does not explicitly contrast this endpoint with list_leads or list_examinees, but the behavior description and mention of report results make the intended use clear.

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

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

Annotations already cover read-only and non-destructive behavior, so the description adds useful context without needing to repeat safety. It clarifies active-only results, the public library scope, field set, and most-used-first ordering, which helps set expectations for what the call returns.

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 focused sentences with no filler. The first sentence states what the tool lists; the second gives the recommended next action. The key scope information is front-loaded.

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

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

With a full input schema, output schema availability, and annotations defining read-only/non-destructive behavior, there is no meaningful gap in what an agent needs to select and invoke the tool. The description also connects it to the logical follow-up tool.

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

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

Schema coverage is 100%, so the schema already documents limit, scene, categoryId, isRecommended, and titleContains. The description adds workflow-level context about using the template id afterward, but it does not need to add parameter details because the schema fully handles that.

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 object: it lists active templates from the public template library, and enumerates the fields returned. This clearly distinguishes it from list_forms and create_form_from_template because it identifies templates as the resource rather than forms.

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

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

The description explicitly tells the agent when to use the tool: 'Use this to find a template, then call create_form_from_template with its id.' It also gives the decision criterion ('when a suitable template exists'). It stops short of saying when not to use it or naming an alternative such as create_form.

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

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

Annotations already indicate the tool is not read-only and not destructive; the description adds the nuance that to move to the front or end you must reference the current first/last field's code. It discloses the requirement to reference existing codes and the positional behavior, 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?

Three sentences with minimal redundancy. It leads with the purpose, then explains the mechanism, and finishes with the front/end special cases. Each sentence earns its place, though it could combine the front/end guidance more tightly.

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 high schema coverage and existing output schema, the description covers all essential mechanics: what to move, how to specify position, and how to handle front/end cases. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds meaning by clarifying that 'after' and 'before' are mutually exclusive ('choose either'), and by explaining how to achieve front/end moves using current boundary codes—details not present in the schema.

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

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

The description names a specific action ('Move'), a specific resource ('existing item (question, page break or display block)'), and explains the positional mechanics with 'after' and 'before'. It clearly separates this from sibling add/delete/update tools by focusing on repositioning.

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

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

The description implicitly defines when to use it (to change an item's position) and gives concrete instructions for both relative moves and front/end placement. It does not explicitly name alternatives, but the tool's purpose is self-evident given the sibling set, so an agent can correctly select 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 mark readOnlyHint=true and destructiveHint=false, and the description adds substantial context around that: the tool never sees the image bytes, the returned URL is short-lived, uploads over 5MB are rejected, and the optional fileSize is checked up front against the 5MB cap and storage quota. It also exposes the subtle asymmetry that while this call itself is read-only, the overall workflow is a mutation performed via the direct PUT — which resolves any confusion the readOnlyHint could cause.

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

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

The description is front-loaded with the key concept ('Step 1 of 2... returns a presigned URL... does NOT receive image bytes') and the numbered workflow is clearly structured. It is a bit long and repeats the 5MB rule a couple of times, and the curl example is generous in detail, but every major section earns its place for a tool with a non-obvious two-step protocol.

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

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

For a tool with a complex presigned-URL flow, the description is effectively a complete operating manual: preconditions (temp file, compression, allowed MIME), the exact invocation, the follow-up finalize call, and cleanup. An output schema exists and will specify return fields, so the description doesn't need to — the only marginal omission (what to do on a failed PUT status) is below the bar for an MCP-tool description.

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, and the description adds value beyond the schema: it clarifies fileSize should be the post-compression size ('the file you will actually upload, after any compression' is expanded by the compression step instructions), and it ties mimeType to the requirement that the PUT Header's Content-Type must match. It doesn't deeply enumerate each parameter, but with a fully documented schema that burden is already carried.

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 starts with a concrete, scoped purpose: 'Step 1 of 2 for adding an image (PNG / JPEG / GIF / WebP) to the current team media library.' It explicitly distinguishes its contract — it does NOT receive image bytes, it returns a presigned URL — and the sibling finalize_image_upload is directly named, so an agent immediately knows what this tool is and what it is not.

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

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

The description provides a complete procedural guide: compress/downscale any file >5MB first (with concrete sips/magick examples), call this tool with filename/mimeType/fileSize, HTTP PUT the file to the returned uploadUrl, then call finalize_image_upload, then delete the temp file. It also states hard applicability rules (5MB cap, four allowed MIME types) and explicitly names the required follow-up sibling, so an agent knows exactly when and how 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?

Beyond the annotations, the description discloses concrete behavioral consequences: the attendee is emailed, the 24-hour reminder is re-armed, and a booking.rescheduled integration event fires. It also explains rejection conditions, which is valuable context for a mutating operation that is not marked destructive.

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

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

Four dense sentences cover purpose, required prerequisite call, parameter constraints, side effects, and failure conditions without wasted words. The most important scoping information comes first and the practical how-to guidance is front-loaded.

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

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

The description is complete for a two-parameter mutation with an output schema: it states preconditions, valid input origin, side effects, event behavior, and rejection cases. Nothing an agent needs to call this tool correctly or anticipate failures is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds useful context by connecting bookingId to get_booking_availability and specifying that startAt must be selected from that call's slots, but most of the parameter meaning is already present in the schema.

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

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

The description opens with a specific verb-plus-resource statement: 'Move a confirmed booking of the current team to a different time, as the organiser.' This clearly distinguishes it from siblings like get_booking_availability, review_booking, and update_booking_status by focusing on the rescheduling action and the organizer/team scope.

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

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

The description gives explicit guidance: call get_booking_availability with this bookingId first, pick a startAt from its slots, and provide that as the new time. It also states when it will not work: rejected if the slot was taken or if the respondent already has another active booking, and only applies to confirmed/scheduled bookings.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavioral details: the restore operation's authorization requirements and its error condition when the form is not trashed. It does not fully explore side effects, but for a single-parameter restore action with an output schema, this is substantive additional context.

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

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

The description is two tight sentences with no filler. It front-loads the core purpose ('Restore a form from the trash'), then adds the inverse-operation reference and the key constraints. Every clause earns its place.

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

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

For a low-complexity tool with one fully documented parameter, an output schema, and annotations indicating mutation but non-destructiveness, the description provides sufficient context: purpose, scope, permissions, and failure condition. The agent has everything needed to decide whether and how to invoke restore_form correctly.

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

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

Schema description coverage is 100%: formId is documented as 'The form UUID to restore from trash'. The tool description does not add further parameter-level detail, but nor is it required to because the schema already fully explains the only parameter. Baseline 3 is appropriate given the high coverage.

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

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

The description clearly states the operation: 'Restore a form from the trash in the current team'. It explicitly frames it as 'undo delete_form', which distinguishes it from both delete_form and the various create/update siblings. The verb and resource are 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 gives explicit conditions for use: it is the inverse of delete_form, applies within the current team, and is only permitted for the form owner or team owner/admin. It also states when it will fail ('errors if the form is not in the trash'), giving the agent clear call-time guardrails.

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 enriches the annotations with real behavioral detail: approval sends confirmation with the meeting address, declining sends a note, expired requests cannot be approved, meeting link/instructions may fall back to team settings, and access is limited to owner/admin/lead owner. This is exactly the context beyond readOnly/destructive hints that is useful.

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

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

Every sentence carries distinct information: the decision action, notification side effects, state constraints, per-meeting overrides, and authorization. It is dense yet not bloated, and it front-loads the core purpose.

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

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

Given the output schema is present and the input schema is fully documented, the description covers all critical decision-relevant context: status preconditions, time-based limitation, side effects, optional parameter implications, and permission rules. Nothing essential is missing.

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

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

Schema coverage is 100%, and each parameter has a descriptive schema entry already. The description adds some usage context around approval vs decline behavior, but it largely mirrors the schema text for meetingLink, meetingInstructions, and declineReason. Thus it meets but does not exceed the baseline for complete schema coverage.

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

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

The description clearly states a specific action ('Approve or decline'), a specific resource ('a pending booking request'), and the current team scope. It differentiates the tool from siblings like update_booking_status by specifying the pending-status condition and the approval/decline decision structure.

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

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

It provides explicit conditions: only pending bookings can be reviewed, and past-dated requests can only be declined. It does not name sibling alternatives directly, but the conditions on booking status effectively define when this tool is appropriate.

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, so the description carries the behavioral burden and it excels: it discloses partial-update behavior (omitted title/radar settings are kept), dimension code stability rules, the removal constraint for dimensions referenced by question dimensionScores or report.formula, scene-dependent treatment of formula/fieldCodes, and the standardScore auto-computation defaults. Notably it tempers destructiveHint=false by explaining exactly what can and cannot be removed, with no contradiction to 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?

A single dense paragraph of roughly 230 words that is front-loaded with the core purpose and where every sentence carries operational information. It loses one point because the dense wall-of-text formatting makes scene-specific rules harder to scan — short scene-labeled segments or bullets would improve parseability — but there is no padding or redundancy.

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

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

For a tool with 5 parameters, nested dimension objects, two scene variants, and an output schema, the description covers everything an agent needs to call it correctly: prerequisites, unsupported forms, preservation semantics, code stability, removal constraints, and clearing behavior. Return values are already handled by the output schema, so their absence from the description is not a gap. The only minor omission is explicit error behavior for invalid references, which the schema partially covers ('Each code must exist in the form').

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, and the description adds meaningful cross-parameter semantics beyond individual schema descriptions: which parameters apply in which scene, how formula and fieldCodes interact, how standardScore defaults are derived, and how the empty dimensions array triggers a clear. It does not need to restate per-field constraints since the schema already documents them, but the scene-conditional behavior is genuine added value, warranting a 4.

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 pair — 'Set the multi-dimension analysis (form.report.dimensionAnalysis) of a form' — and immediately clarifies the exact mutation semantics: replaces the dimension list while preserving overallAnalysis. It is clearly distinguishable from all siblings (update_form, create_form, get_form) because it names the precise report field it operates on and states its unsupported form type.

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 conditions per scene ('In the knowledge_quiz scene each dimension needs fieldCodes; in the scored_quiz scene a formula is optional'), an explicit when-not ('Not supported for random_knowledge_quiz forms'), a prerequisite ('Call get_form first to read the question and dimension codes'), and a clear usage pattern for clearing ('Pass an empty dimensions array'). This is actionable routing guidance, not just a generic statement of purpose.

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 discloses semantics beyond the annotations: 'replace' overwrites the whole tag set, 'add' and 'remove' have batch-oriented behavior, 'remove' accepts stale codes, and changes are recorded on each lead's timeline. It also states the tag-code existence requirement without relying on schema descriptions alone.

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

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

The description is concise and efficiently structured: it front-loads the tool's purpose, then packs the most important operational constraints into a small number of sentences. Every sentence earns its place, and the mode-specific guidance is clear without being bloated.

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

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

For a mutation tool with a mode enum, array limits, team-scoped behavior, and a business-library dependency, the description is complete. It explains when to use each mode, how tags are validated, what happens to existing tags, and where the changes are recorded; an output schema also exists, so return-value details are not required in the description.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds valuable operational meaning, especially for 'mode' behavior and batch expectations, but since the schema interface already carries descriptive parameter docs, the description's extra contribution is strong but not fully 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 specific verb and resource: 'Set the colour tags on one or more leads of the current team.' It clearly identifies the action, the target entity (leads), and the team scope, which makes the tool distinguishable from siblings like update_lead, assign_leads, and list_lead_settings.

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

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

The description gives explicit operational guidance: pass all lead ids in one call, do not loop, respect the 50-lead maximum, and select the mode based on single-lead edits versus batch operations. It explains why using 'replace' for batches can wipe other people's tags, and it names list_lead_settings.tags as the source for valid tag codes.

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 (which only say the tool is not read-only and not destructive), the description discloses the key behavioral trait that the switch persists across sessions, and the access requirement that the caller must be a member. No contradiction with annotations exists, as the readOnlyHint=false is consistent with a state-changing 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?

The description is exactly three short sentences: the action, the persistence effect, and the membership precondition. Every sentence carries distinct information, the most important facts are front-loaded, and there is no redundant 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 tool is simple (one parameter) with a rich schema and an output schema available, so the description's coverage of purpose, side-effect persistence, and eligibility precondition is sufficient. Nothing an agent needs to call it correctly appears to be missing.

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

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

Schema description coverage is 100% with the sole parameter (tenantId) well documented, including a pointer to list_my_tenants for discovery. The description adds no additional parameter-level information, so with full schema coverage baseline of 3 is appropriate.

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

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

The description states a specific verb (Switch), a precise resource (active team/tenant), and the exact scope (for this token). It clearly distinguishes itself from the get_active_tenant (read) and list_my_tenants (discover) siblings.

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

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

The description provides a precondition (caller must be a member of the target team) and states that the change persists across sessions, which implies when it should be used. However, it does not explicitly name alternative tools or state when not to use it - the cue to use list_my_tenants for discovery lives only in the parameter schema rather than in the description.

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

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

The description discloses important behavioral side effects beyond annotations: cancellation notifies the attendee by email and fires an integration event, while completed/no_show do not contact the attendee. It also explains the difference between status transitions. This adds significant context not available in the annotations alone.

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

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

The description is front-loaded with the core purpose, then systematically adds preconditions, side effects, and an alternative. It is a bit longer than minimal, but every sentence is necessary and adds distinct value.

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

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

Given the presence of an output schema and the annotations, the description provides everything an agent needs: valid statuses, eligibility conditions, side effects, and sibling routing. Nothing critical is missing for correct invocation.

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

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

Although the schema already covers all parameters (100%) and defines enum values, the description adds clear behavioral nuances for each status (e.g., cancellation triggers notification, completed/no_show are internal). It enriches the schema's plain definitions with operational 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 verb ('close out') and the resource ('a confirmed booking of the current team'), then enumerates the exact acceptable outcomes. It also distinguishes itself from the sibling review_booking by explicitly naming the tool for pending requests.

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

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

The description clearly specifies the precondition: only works on bookings with status 'scheduled', and adds time-based requirements for completed/no_show. It also gives an explicit exclusion: 'To handle a pending request use review_booking instead'.

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 destructive behavior, but the description goes further by explaining exactly how: customData replaces the whole object, masked values are rejected, and replaying a previously read customData can wipe or corrupt phone fields. This is precisely the kind of behavioral context beyond annotations that an agent needs.

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

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

The description is dense and front-loaded with the operation and resource, followed by a concise list of editable and immutable fields and a distinct warning. It earns its length, though the customData warning partially repeats the input schema's customData description.

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

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

For a destructive mutate operation with a nested customData object, the description provides the essential operational context: identity selection, field editability, validation behavior, and the destructive consequence of echoing masked data. The presence of a full output schema and complete input schema rounds out the tool definition.

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 covers 100% of the parameters, so the schema already handles most semantics. The description adds valuable clarification: email, tenant, and examineeId cannot be changed, customData is validated against field definitions, and readonly/masked values must not be re-sent. This is meaningful but partially redundant with the schema.

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

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

The description uses a specific verb and resource: 'Update an examinee' and states it operates in the current team, identified by examineeId. It also clarifies what is editable versus immutable, which makes the tool's scope distinct from sibling read/list tools like get_examinee and list_examinees.

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

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

It gives a clear prerequisite: the examinee is located by the business ID from list_examinees, and it scopes updates to the current team. It also notes immutable fields. It does not explicitly name alternatives or when-not-to-use scenarios, but for a mutation tool the usage context is established sufficiently.

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

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

The description discloses substantial behavior beyond the annotations: sub-key merge semantics for report and openGraph, empty-string clearing, wholesale replacement of systemText, image-only behavior of landingImage, outcome matching by code, and rejection of removals still referenced. This is far more than the readOnly/destructive hints provide.

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

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

The description is dense but well-organized: purpose and field list first, then cross-cutting semantics, then routing exclusions. Every sentence earns its place, and the length is appropriate for an 11-parameter tool with nested objects.

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 exhaustive schema descriptions, an output schema, and annotations, the description adds exactly the operational context missing from structured fields: merge behavior, constraints, and sibling routing. An agent has what it needs to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the description does not need to compensate. It nevertheless adds cross-cutting value by explaining shared patterns across parameters: media IDs/URLs/empty-string clearing, merge-vs-replace behavior, and language-change restrictions that the schema separates per parameter.

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 ('Update'), a resource ('a form of the current team'), and explicitly enumerates the updatable fields. It also distinguishes itself from sibling operations by routing questions to add_question/update_question/delete_question/move_question and dimensionAnalysis to set_dimension_analysis.

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

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

Provides explicit routing guidance versus related tools and states when language changes are allowed and that scene is immutable. The description also clarifies what this tool is not for, which gives an agent clear selection criteria among siblings.

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

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

Annotations only indicate this is a write operation, leaving the description to carry behavioral context. The description discloses partial-update semantics ('Only the keys you pass are changed') and explains real-world consequences of settings, such as lead capture, completion rate versus lead quality, and organic sharing. It does not mention side effects like slug breakage in the description itself, though the schema covers that in detail.

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

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

The description is long but front-loaded with purpose and alternatives before the field list. Each parenthetical earns its place by adding decision-relevant context rather than repeating schema details. The density is justified by the number of editable settings, and there is no filler.

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