GuiaFlow

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

Adds real behavior beyond the annotations: it responds with warnings when it adjusts input (e.g., the click point is moved inside the highlight), only the video link is stored (nothing is uploaded), and the YouTube/Vimeo player loads only on play. Annotations already declare non-read-only, non-destructive, non-idempotent, so the bar is lower, but the description pays it with concrete side-effect 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?

Three front-loaded sentences: the core definition first, the video variant second, the warning behavior third. Dense but every clause (fractions, optional image, adjustment warnings) carries information the agent needs.

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

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

For a 17-parameter write tool with no output schema, it covers the primary paths (image step, video step, adjustments) and the warning response. It does not say what is returned (e.g., the new step's id) and only lightly touches ordering/scene behavior, which the schema handles.

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 94%, so the baseline is 3; the description still adds meaning by framing image/highlight/click as fractions 0..1 of the image and by clarifying that with a video the cover becomes the image and image is optional. It does not restate the remaining 14 parameters, which the schema already documents.

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

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

States a specific verb+resource ('Adiciona um passo ao tour') and enumerates the constituent parts of a step (captura, destaque, ponto do clique, título/texto), so the agent knows exactly what is being created. It does not explicitly differentiate from update_step or delete_step, so sibling routing is left to inference.

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

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

Gives conditional guidance for one variant – use video for a video step (image becomes optional) – and implies screen vs slide behavior. It never says when to use this instead of update_step or reorder_steps, nor any precondition such as the tour having to exist or being unpublished.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds the post-creation workflow but omits non-obvious behavior such as whether duplicate names are allowed, whether the call fails on quota limits, and what identifier is returned for the follow-up call.

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 short sentences with zero waste; the core action is front-loaded and the workflow hint follows immediately. Nothing is padded or repetitive.

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

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

For a simple two-parameter creation tool with annotations present and no output schema, the description is mostly adequate. The key gap is that it directs the agent to move_tour_to_client without noting that the created client's identifier is needed for that call, leaving the handoff 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 both parameters (name, logoUrl) are already documented in the schema with constraints. The description adds nothing about parameter meaning, formats, or defaults, so the baseline 3 applies.

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

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

States a specific verb and resource ('Cria um cliente/marca na conta'), which is unambiguous and clearly distinguishes it from list_clients or create_tour. It also names the natural follow-up sibling, move_tour_to_client, though it does not explicitly contrast with any alternative creation path.

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 second sentence gives a concrete next-step workflow ('Depois use move_tour_to_client'), which is real usage guidance beyond the definition. However, it never says when NOT to create a client, what prerequisites exist (plan limits, permissions), or how it relates to list_clients for checking duplicates.

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 non-readonly, non-idempotent, non-destructive), the description discloses expiry limits and defaults, reusability of the link, which webhook events carry the progress plus the external.id/source "api" fields, the one-time notice shown to the person, the returned fields, and the revoke endpoint. That is genuinely useful behavioral context an agent would otherwise have to guess.

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

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

Front-loaded with the purpose, then constraints, effects, return values and revocation in a compact block. It is dense but every sentence carries operational information; only the expiry restatement overlaps the schema.

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

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

With no output schema, the description still names the returned url, expiresAt and jti, and explains how downstream progress is observed and how to revoke a link. Nothing essential for calling this three-parameter 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: externalId is what ties the link to webhook payloads via external.id, and the warning not to put an email or name in it clarifies the "sem PII" constraint. expiresIn is largely restated from 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: it generates a /p link for a published tour that identifies the person by externalId, without a form. That is enough to separate it from every sibling here (publish, set_lead_capture, create_client) without opening any schema.

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

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

It makes the key usage context explicit: the tour must be published, no form is shown, and the link can be opened repeatedly. It never names an alternative path (for example form-based lead capture) or states when not to use it, so the guidance is clear but not complete.

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

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

The description adds useful behavior beyond the annotations: the tour appears in the editor with the "criado por agente" label, and the response includes scaffold.scenes with scene numbers to pass to add_step. It still leaves some ambiguity about how mode and template interact when both are supplied, but the main side effects and follow-up workflow are disclosed.

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

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

The description is front-loaded with the core action, then gives the follow-up step, template guidance, and mode behavior in a compact sequence. The template details are dense but each one helps the agent choose the right parameter 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?

For a creation tool with no output schema, the description is fairly complete: it explains the immediate side effect, the next tool to call, and the shape of the scaffold.scenes response. The remaining gap is that theme behavior and template/mode precedence are not addressed, though the schema covers theme fields.

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 75%, so the schema already documents most parameters. The description adds practical meaning for template by listing scene names and intended use cases, and notes that mode can be changed later in the editor. Theme is not mentioned in the description, but it is fully covered by 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: "Cria um tour vazio na conta". It also distinguishes the next action by naming add_step for captures, so the agent can tell this is the creation step rather than a step-adding or editing tool.

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

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

It explicitly says to use add_step after creating the tour for each capture, and it routes photo tours to specific templates with detailed use cases. The alternatives are named and the selection criteria are clear, including the default "software" guided-tour case.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond them by disclosing the cascade side effect: the underlying capture is dropped from the project when no other step references it, which an agent cannot infer from 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 front-loaded sentence stating the action first and the conditional side effect second. There is no filler.

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

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

For a two-parameter delete with no output schema, the description covers the action and the key destructive side effect. The remaining gap is the undocumented stepId parameter and the absence of any prerequisite/irreversibility note, but the essential behavior is conveyed.

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 only 50%: tourId is documented in the schema (including how to obtain it) but stepId is a bare string. The description mentions neither parameter and adds no meaning, so the uncovered parameter remains unexplained.

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

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

States a precise verb+resource (remove a step from a tour) and adds the conditional scope of the removal. It is unambiguously distinct from siblings like add_step, update_step and reorder_steps, so an agent can select it without opening the schema.

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

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

Provides no when-to-use, when-not-to-use, or alternative guidance. Nothing tells the agent whether this is preferred over update_step or what prerequisites (published state, ownership) apply before deleting.

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

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

The annotations only provide the generic safety profile (not read-only, not destructive, not idempotent, open world). The description goes well beyond them, disclosing that the generated audio is written into the step, that step duration is extended, that the monthly Pro audio quota is consumed, and that video steps return 400. It does not cover authentication requirements or concurrency behavior, which is the only notable gap.

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

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

The description is a single dense paragraph. It places the most important information first (what is generated and where the output goes), then the quota, then failure modes; almost every clause carries new information for an agent.

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

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

For a mutating tool with no output schema, the description covers the important consequences: audio persistence, step duration change, quota consumption, caching, and the 400 error path. The only gap is a precise description of the success response, which matters less because the tool has no output schema.

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

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

Schema description coverage is 83%, so the baseline would be 3. The description adds value beyond the schema by explaining the text resolution precedence among the text, narrationScript, and title+text sources, which the schema does not spell out; the lang parameter's caching behavior is covered inside 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 and resource (generates spoken narration for a step), the output format (MP3 mono 64 kbps, 24 kHz), and the side effect (audio is attached to the step and the step's duration grows to fit it). That makes it clearly distinguishable from the sibling generate_step_text, which produces text rather than TTS audio.

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 context is clear: it draws on the monthly Pro audio quota of 30 min/month, and steps containing YouTube/Vimeo video cannot be narrated and return 400 with a stated reason. It does not explicitly name which sibling to use instead (for example generate_step_text or translate_tour), so it stops short of full 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 annotations (readOnlyHint=false, openWorldHint=true), the description discloses high-value behavior: it consumes one monthly Pro quota credit (100/month), save=false returns a suggestion without writing, alt text is only written when the step lacks one, and video steps get no narration. It stops short of saying whether save=true overwrites existing title/text.

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?

One front-loaded paragraph that opens with the core action and then layers the quota, save, narration and alt caveats. It is dense but every clause carries information; the long compound sentences cost it a point versus a crisper structure.

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 7-parameter generation tool with no output schema, the description covers the mutation semantics, quota cost and conditional writes that an agent needs. It does not describe what a save=false call returns, which is the main remaining gap.

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

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

Schema coverage is already 86%, so the baseline is 3; the description adds real semantics on top — the side effect of the save flag ('só sugere'), the conditional alt behavior, and the video-step exception that governs narrationScript. It leaves useImage and instructions with only what the schema already says.

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

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

The description uses a specific verb+resource ('escreve título e texto do balão' a partir da captura do passo) and makes clear it is an AI generation tool distinct from update_step/add_step. It overlaps with the sibling generate_narration by noting narrationScript, but never names that sibling or tells the agent when to prefer it over this one.

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

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

Usage is implied rather than prescribed: 'a IA olha a captura e escreve' tells the agent the scenario, and 'save:false só sugere' hints at a preview mode. However, there is no explicit when-to-use/when-not framing and no routing away from generate_narration or update_step, so the agent must infer the boundaries.

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, idempotentHint, non-destructive and closed-world. The description adds genuinely new context: the 30-day default window, the São Paulo timezone interpretation, and the guarantee that no personal data is returned — a privacy-relevant disclosure not available in structured fields.

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 with semicolon-delimited clauses; purpose and the two modes are front-loaded and every clause carries information. Slightly heavy as one block, but no wasted sentences.

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

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

There is no output schema, so the description carries the burden of describing returns — and it enumerates them (totals, daily series, per-step funnel, origins, per-link summary). Combined with default window and timezone, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% (baseline 3), but the description goes further by explaining the semantic consequence of tourId (per-tour detail vs. per-link summary) and supplying the implicit default for from/to that the schema does not state.

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 resource ('Estatísticas do link permanente') and splits behavior into two clearly described modes (with vs. without tourId), naming exactly what each returns. An agent can tell this is the read-only analytics tool with no ambiguity against the mutation-oriented 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?

Explicitly conditions usage: pass tourId for per-tour analytics, omit it for a per-published-link summary, and states the default window when no dates are given. No alternative tool is named, but none exists in the sibling list, so the guidance is sufficient.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value by disclosing the shape of the returned tour object (steps, theme, lead capture, CTA, published link), which matters because there is no output schema.

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

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

One dense sentence that front-loads the action and then lists the payload fields. Nothing is wasted, though the parenthetical "(com ids, destaque e clique em 0..1)" is terse to the point of being slightly cryptic.

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

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

With no output schema, the description usefully compensates by enumerating what the returned tour contains. For a single-parameter read tool with full annotation coverage, this is close to sufficient; error cases such as an unknown tourId are unaddressed but minor.

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

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

Schema description coverage is 100% and the single tourId parameter is fully documented in the schema (including its provenance from create_tour or list_tours). The description adds no further parameter meaning, 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?

States a specific verb ("Mostra") and resource ("um tour"), and enumerates the returned payload (steps with ids/highlight/click, theme, lead capture, final CTA, published link). This is clearly distinguishable from mutating siblings like create_tour or set_theme, though it never explicitly contrasts itself with list_tours.

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?

There is no explicit when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as list_tours for browsing versus this tool for a single tour. Usage is only inferable from the name and the tourId parameter.

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 this as a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context by explaining that the result includes each client's tour count, which is not conveyed by annotations or schema.

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

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

A single front-loaded sentence conveys the resource, scope, and return content with no wasted text. The parenthetical adds relevant context without bloating the definition.

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

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

For a zero-parameter list tool with no output schema, the description is largely complete: it identifies what is returned, including tour counts. Minor gaps such as ordering or empty-account behavior are not critical 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 tool takes zero parameters, so there are no parameter semantics for the description to clarify. Baseline 4 is appropriate because the schema is empty and complete for this operation.

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 in Portuguese: it lists the account's clients/brands and includes how many tours each has. This clearly identifies the operation beyond the title, though it does not explicitly contrast with siblings like create_client or list_tours.

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 implied by the parenthetical that agencies organize tours by client, which suggests when a client list is useful. However, there is no explicit when-to-use/when-not guidance and no named alternative such as list_tours.

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 safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower. The description does add the newest-first ordering, a genuine behavioral trait not present in the schema, but says nothing about pagination, default page size, or whether the 200 limit truncates silently.

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 short sentence with the scope and ordering front-loaded and zero filler. It is efficient rather than padded, though it is terse enough to leave the limit parameter and result size unaddressed.

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-optional-parameter read tool with full annotations and no output schema, the basic contract is covered. However, the default/effective limit and what the response contains (ids usable as input to get_tour, move_tour_to_client, etc.) are left for the agent to guess.

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 only 50%: clientId is documented (including the special 'none' value, though the description adds nothing to it) while 'limit' has no description at all in the schema. The description does not compensate by explaining the limit range, default value, or filtering semantics, so the undocumented half stays opaque.

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?

Specific verb+resource ('Lista os tours (projetos)') plus a scope ('da conta') and an ordering guarantee ('do mais recente para o mais antigo'). It is clearly distinguishable from mutating siblings like create_tour or get_tour, but it never explicitly contrasts itself with get_tour for single-item retrieval.

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 never says when to prefer this over get_tour (single tour) or list_clients, nor does it state prerequisites such as needing a clientId to narrow results. The only implicit signal is the word 'Lista' plus the account scope; an agent must infer the rest from the sibling names.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds real behavioral context not derivable from those hints: that assigning moves the tour out of its previous client and that null re-homes it to the "Sem cliente" bucket.

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 short sentences with zero filler, and the primary action is front-loaded ahead of the edge case. Nothing repeats the name, title, or schema.

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

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

For a simple two-required-parameter mutation with no output schema, the description covers the action and the only non-obvious input case. Missing only the side conditions an agent might need, such as whether the target client must exist or whether republishing is required.

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 earns above that by giving null clientId a concrete meaning (unassign to "Sem cliente") where the schema only permits null without explaining it. tourId is left to the schema, which documents its source (create_tour / list_tours).

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

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

States a specific verb and resource ("Coloca o tour num cliente") and immediately covers the negative case (clientId null removes the tour). No sibling tool performs client assignment, so the action is unambiguous against the surrounding tour/client 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 tells the agent how to detach a tour (pass null), which is genuine usage guidance. However, it never says when this tool should be chosen over alternatives, nor any prerequisite such as the client existing or the tour's publish state.

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

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

Goes beyond annotations (idempotentHint/readOnlyHint=false) by disclosing that publishing updates the existing link if one exists, auto-generates an og:image cover, and that previews expire in 7 days. Doesn't mention required permissions or rate limits, so not a 5.

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

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

Three dense, front-loaded sentences with no filler; each sentence carries distinct information (output, idempotent update, dryRun workflow, og:image). Slightly run-on but efficient.

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

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

With no output schema, the description correctly carries the return-value burden by specifying the URL, embed code, and preview.url. Combined with the idempotency and cover-generation notes, an agent has everything needed to invoke and interpret it.

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

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

Schema coverage is 67%; the description supplies meaning for dryRun (validation + preview.url) that the schema leaves undocumented, and notes title defaults to the tour name (which the schema also states). It adds genuine value over structured fields.

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

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

States a specific verb+resource: publishes the tour to a permanent link and returns the URL and embed code. It clearly distinguishes itself from siblings (e.g., unpublish) by naming the exact artifact produced (guiaflow.pro/p/… link).

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 tells the agent to call with dryRun:true to validate and show a 7-day preview before publishing, which is a clear recommended workflow. It lacks an explicit statement of when NOT to publish or a named alternative (e.g., unpublish), so it falls short of 5.

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

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

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description still adds real behavioral context by making clear this is a full reorder requiring all step ids in the target order, which is the key trait an agent must know before calling.

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 short sentences, zero filler, with the action stated first and the input requirement immediately after. Nothing is redundant with the schema or annotations.

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 mutation tool with no output schema, the description covers the essential semantics: it is a full ordering replacement and requires every step id. It omits edge-case behavior (what happens to steps not included, ordering validation failures), which keeps it from being fully complete.

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

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

Schema coverage is 50% - tourId is documented in the schema but stepIds has no property description. The description compensates by explaining that stepIds is the complete, ordered list of ids, which is exactly the missing semantic. It does not clarify the 'ids do tour' wording versus step ids, a minor ambiguity.

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

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

States a specific verb and resource: 'Define a nova ordem dos passos' tells the agent this rewrites step ordering for a tour, which clearly separates it from add_step, delete_step, and update_step. It stops short of naming any sibling explicitly, so it is clear but not fully differentiated in-text.

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 second sentence gives an operational instruction ('envie todos os ids do tour, na ordem desejada'), which implies the usage pattern of a full-replacement reorder. However there is no when-to-use/when-not-to-use guidance and no reference to alternatives like update_step, so the routing signal is only implied.

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

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

Annotations already declare idempotent=true, destructive=false, and non-readonly, so the safety profile is covered. The description adds genuinely new behavior: partial-update semantics ('Só muda os campos enviados'), which elements persist across modes (initial lead step and final card), and the cross-tool dependency on set_end_cta for the sticky button.

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?

One dense paragraph that front-loads the core action and mode meanings before the persistence note. It is a bit run-on and the trailing editor-location hint ('⚙ → Modo de exibição') is UI trivia that doesn't help an agent invoke the tool, but overall little 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 4-param mutation with no output schema and full annotation coverage, the description supplies mode semantics, partial-update behavior, preserved elements, and the set_end_cta prerequisite. An agent has everything needed to call it correctly without further lookup.

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

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

With 100% schema coverage the baseline is 3, but the description adds value beyond the schema: sceneNames become gallery sections, stickyWhatsAppStep borrows the number configured in set_end_cta, and the mode choice changes which UI features exist (no balloons/narration in gallery). Only 'tourId' is left entirely to the schema, which is appropriate.

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

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

States a specific verb+resource (defines how the tour is displayed) and covers all three configurable facets: mode (guided/gallery), the sticky WhatsApp button, and scene names. The scope sentence 'Só muda os campos enviados' plus 'O passo inicial (lead) e o cartão final continuam nos dois modos' makes clear what this tool does and does not control, distinguishing it from set_end_cta and set_theme.

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 explains what each mode is for (guided tour vs full-screen photo gallery for properties/vehicles/products/catalogs) and states the prerequisite that stickyWhatsAppFromStep only shows when the final WhatsApp CTA is enabled via set_end_cta. It doesn't explicitly say when to prefer this over set_theme or set_end_cta, but the context is clear enough to 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 declare readOnly=false, idempotent=true and destructive=false, so the mutation/safety profile is covered elsewhere. The description usefully adds the toggle semantics via enabled:false, but does not say whether existing card configuration is replaced or merged, nor what happens if neither whatsapp nor link is supplied.

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 front-loaded sentence with the core action first and the toggling and formatting caveats in parentheses. Dense but every clause carries information; 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 7-parameter mutation with nested objects and no output schema, the agent would still want clarity on how whatsapp and link interact and what 'disabling' preserves, but the description plus annotations otherwise give enough to call the tool safely and correctly.

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

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

Schema description coverage is only 29%, so the description must compensate and it partly does: it explains the E.164 phone format with an example and constrains link to https. However, it says nothing about title, text (the schema itself already documents light markdown), the optional labels, whatsapp.message, or showReplay.

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

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

States a specific verb and resource: enables/disables the final CTA card with WhatsApp and/or link buttons. This is clearly distinct from the sibling `set_*` tools (set_theme, set_hubspot, set_lead_capture), though the description itself never draws that contrast.

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 only implied: the parenthetical 'ou desliga com enabled:false' signals how to turn the card off, and 'e/ou' implies WhatsApp and link can be used independently. There is no explicit when-to-use statement, no prerequisites, and no mention of when to prefer this over other end-of-tour settings.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is partly covered. The description adds real value beyond that: credential encryption, response limited to tokenLast4/method/oauthAvailable, 503 config_missing, OAuth refresh revocation on remove, and the shared 20-attempt retry queue. However, there is tension: 'remove:true apaga' (and revokes the refresh token) reads as a delete against a destructiveHint=false annotation. It discloses what is destroyed, which earns credit, but the idempotentHint=true claim isn't clearly reconciled with the state-changing OAuth/token-swap modes.

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?

Dense but front-loaded: the core connection rule leads, then per-mode detail, then side effects. Every sentence adds operational information, though the LGPD/mapping paragraph could be tightened.

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

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

For a 9-parameter, nested-object tool with no output schema, it covers the return shape (tokenLast4, method, oauthAvailable), error cases (503 config_missing), mapping defaults, and what each flag does. An agent has enough to call it correctly without guessing.

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 78% schema description coverage the baseline is 3, and the description goes further by documenting defaults (mapping uses guiaflow_* ), the empty-string-to-disable rule for mapping fields, the pat- token format, and the code+state pairing. These are semantics the schema does not fully spell out.

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

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

States a specific verb and resource ('Conecta o link permanente já publicado ao HubSpot') and immediately scopes it ('Uma conexão por link, method oauth ou private_app'). It is clearly distinguishable from siblings like set_rd_station and set_lead_webhook by naming the target integration.

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 maps each mode to its trigger: authorize:true for OAuth, a pat- token for private app, remove:true to disconnect, sendTest:true to write a test contact. It also states the mutual-exclusion rule ('conectar por um método substitui o outro'), so an agent knows exactly which path to pick.

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 the non-destructive, idempotent, non-readOnly profile, so the bar is lower; the description still adds real context beyond them by naming the side effect (contacts land in the owner's Leads editor) and the precondition that it only functions on the permanent link. It does not say what happens to already-collected leads when disabling.

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

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

Three short sentences, with the enable/disable behavior front-loaded ahead of the destination and the link constraint. No filler, though the 'link permanente' caveat could have been phrased as an explicit conditional.

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

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

For a 9-parameter mutation tool with no output schema and a nested fields object, the description covers the core concept, the toggle mechanism, the data destination and the main precondition. Missing only minor detail on custom label parameters and disable-time effects, which are low-risk 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 44%, so the description must carry some weight. It clarifies the semantics of enabled (false turns it off) and names the three contact fields the step collects, which maps onto the nested fields object, but it adds nothing about title, text, skipLabel or submitLabel, which are undocumented in the schema too.

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: it turns on (or off with enabled:false) the initial step that collects name/email/phone before the tour. That distinguishes it from set_lead_webhook and set_end_cta, which sound adjacent but are never named, so sibling differentiation is only implicit.

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 one strong usage constraint — 'Só funciona no link permanente' — which tells the agent when the call will succeed, and it explains how to disable via enabled:false. It never says when to prefer this over set_lead_webhook or set_end_cta, so the choice between siblings is left to inference.

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

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

Adds substantial context beyond the annotations: HTTPS on port 443, secret format, anonymous sessions arriving with external:null, the 30-second minimum interval on session.progress, and that the same webhook-id repeats on delivery failure. One mild tension exists between 'remove:true apaga' and destructiveHint=false, though that removal is a config teardown rather than record destruction, so it reads as disclosure rather than contradiction.

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

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

Front-loaded with purpose and constraint, then structured by topic (URL, secret, events, training, remove/test, retries). It is dense and semicolon-heavy, and the event taxonomy in the middle is packed tightly, but no sentence is 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 an 8-parameter open-world mutation tool with no output schema, the description supplies the payload semantics, delivery/retry behavior, rate limits, and secret handling an agent needs to configure it correctly. Remaining gaps are the enabled flag and what the response returns (e.g., generated secret or webhook id).

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 schema coverage at 50%, the description compensates for most gaps: it explains url (https/443), secret (whsec_ or omit to auto-generate), and the meaning of each event value including what each training event carries. The enabled and rotateSecret parameters are left to the schema, and enabled is undocumented in both places.

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

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

States a specific verb and resource: 'Configura o webhook do link permanente já publicado', plus the constraint that the tour must already be published. It is distinguishable from sibling integration tools like set_hubspot and set_rd_station, though it never says explicitly how it differs from them.

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

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

Gives clear operational conditions: works on an already-published permanent link, a secret may be pasted (whsec_) or omitted for generation, remove:true deletes, and sendTest:true fires a lead.test event. It does not name an alternative tool or an exclusion case (e.g., when to use set_hubspot/set_lead_capture instead), which keeps it below a 5.

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

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

The description says remove:true apaga (deletes), but annotations declare destructiveHint=false, which means only additive updates. That is a direct contradiction even though the description otherwise adds useful auth, key-handling, and retry details.

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 front-loaded: purpose first, followed by endpoint/auth, conversion identifier behavior, key handling, remove/test modes, and failure handling. It contains no filler, though several details are compressed into technical shorthand.

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

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

With no output schema but with annotations present, the description covers auth, external endpoint, side effects, key redaction, remove/test behavior, and failure retry limits. It still omits the meaning of enabled and says less about how this relates to sibling lead-capture tools.

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 60%, and the description adds meaningful semantics for apiKey (public App Store key, not OAuth, only keyLast4 returned), remove (deletes), and sendTest (tagged guiaflow-teste conversion). It leaves enabled undefined and mentions conversion_identifier even though that is not an input property.

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

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

States a specific action: connect an already-published permanent link to RD Station Marketing, and adds the concrete side effect that lead.created becomes a CONVERSION. This is much more specific than the sibling tool names and makes the resource clear.

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

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

Implies a prerequisite (the link must already be published) and explains remove and sendTest modes. However, it never explicitly says when to choose this tool over related siblings such as set_lead_webhook or other lead-capture tools.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds essentially nothing beyond that: it does not say whether unspecified colors are preserved, whether preset and explicit colors conflict, or what permissions are needed. Minimum viable given the annotation coverage.

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

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

A single sentence that front-loads the action and then the three input forms, with zero filler. Nothing could be removed without losing meaning.

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

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

For a 4-parameter, fully schema-documented mutation with no output schema, the description is sufficient to invoke the tool correctly, and annotations cover reversibility/idempotency. The only gap is the interaction between preset and explicit colors, which neither description nor schema disambiguates.

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%, including the enum of fonts, the hex pattern, and the preset id list, so the schema does the heavy lifting. The description only mirrors those three parameter groups and adds no precedence or format detail (e.g. what happens when preset and colors are both supplied). 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 names a specific verb ("Muda") and resource ("as cores e a fonte do tour") and enumerates the three ways to do it (preset, colors #RRGGBB, font). It is instantly distinguishable from siblings like set_end_cta or set_translation, though it makes no explicit sibling comparison.

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 only implied: it is clear you call this when you want to restyle a tour, but there is no statement of when to prefer a preset vs raw colors, no prerequisites, and no exclusions. The "e/ou" hints that the three inputs are combinable, which is the only real guidance given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the mutation and safety profile is covered. The description adds that the resulting status is 'reviewed' and enumerates applicable field names per step type, but it does not clarify overwrite/partial-update behavior for omitted fields.

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

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

The description is front-loaded with the main action, then stepId semantics, then field lists. It is dense but efficient, using semicolon-separated lists rather than padding, though the field enumeration is somewhat run-on.

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 four-parameter, all-required mutation with a nested object and no output schema, the description covers the essential input semantics: target language, step target, and valid fields per step type. It omits edge-case behavior such as handling unknown stepIds or partial field updates, which are the main remaining gaps.

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 only 25% (only tourId is documented). The description compensates substantially by defining stepId semantics, including the special 'start'/'end' values, and by listing the allowed fields for step, start, and end steps. It still leaves lang format and nested field value constraints to 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 and resource ('Grava textos traduzidos de um passo num idioma') and explains that the saved status becomes 'reviewed'. It does not explicitly differentiate itself from sibling tools like translate_tour or update_step, so an agent must infer the distinction from the name and fields.

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 explaining that stepId can be a step id or one of the fixed values 'start'/'end', and it lists which fields apply to each step type. However, it gives no explicit when-to-use guidance or alternatives relative to translate_tour, which is the likely sibling for generating translations.

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

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

Goes well beyond the annotations: it discloses that reviewed texts are NOT overwritten unless overwriteReviewed:true, that results carry status 'auto', that each language consumes 1 monthly quota unit, and that Pro projects cap at 3 targets. These are exactly the mutation side-effects and limits an agent needs before invoking.

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 content is front-loaded with the verb and scope, and every clause carries operational information with no filler. The sentences are long and dense (quota, status, overwrite, dryRun all crammed together), which slightly hurts scanability but not content economy.

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 no output schema and only the annotations' safety profile, the description covers scope, side-effects, limits, quota accounting, and the dry-run escape hatch. An agent has everything needed 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?

With 75% schema coverage the schema already documents dryRun and overwriteReviewed, but the description adds meaning: targets are BCP-47 tags with concrete examples ('en', 'es-MX'), the quota cost is per language, and dryRun is framed as a cost preview. It reinforces rather than merely restates the schema.

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

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

States a specific verb (translate) and resource (all tour texts) and enumerates exactly which fields are translated (títulos, descrições, narração, passo inicial/final, botões, consentimento). This clearly distinguishes it from set_translation and generate_narration among the siblings.

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

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

Usage is implied: the description explains that translations are written with status 'auto' and protected against overwriting reviewed text, and that dryRun estimates cost, which sketches the scenario. However, it never explicitly names when to use this instead of set_translation for manual edits, nor states any condition that would steer the agent to an alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description earns credit by naming exactly what is destroyed ('as estatísticas e leads desse link são apagados') and what survives ('O tour continua na conta'). It also discloses the confirm:true prerequisite, which annotations do not carry.

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

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

Three short sentences: the destructive effect leads, scope follows, and the prerequisite is last. No filler and no repetition of the title or schema.

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

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

With destructive behavior, the confirmation gate, and the survival of the tour all covered, and with annotations carrying the safety profile and no output schema to explain, an agent has everything needed to call this correctly.

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

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

tourId is documented in the schema, and confirm's const:true makes it largely self-documenting. The description adds that confirm is mandatory ('Exige confirm:true'), reinforcing the schema at the point of decision, though it adds no new syntax beyond that. At 50% schema coverage this is adequate but not exceptional.

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

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

States a specific verb+resource: takes the permanent link offline and specifies the observable effect ('o /p deixa de abrir'). It also draws a sharp scope boundary ('O tour continua na conta'), which is exactly the distinction an agent needs versus a delete 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 makes the use case clear and implies the boundary condition (link comes down, tour survives), which is the key decision point against deletion. It does not, however, explicitly name a condition or alternative sibling (e.g. publish, or a delete tool) the way a 5 would.

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 mutation, idempotency and non-destructiveness. The description adds genuinely useful behavior beyond them: only the sent fields are changed (true partial update, not replace), and video=null removes the video. It does not mention side effects such as image download/cover generation or that video disables highlight/click (that detail lives only in the schema).

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

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

Two short sentences, zero waste, with the partial-update constraint and the video null behavior front-loaded where an agent will read them first.

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

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

With 18 parameters and no output schema, the description gives enough to call it correctly: what can change, that omitted fields are preserved, and the video null case. Missing only cross-parameter interactions (video overriding highlight/click, image-becomes-cover) which are buried in the schema rather than surfaced.

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 89%, so parameters are already well documented, including the video null-removal and image source rules. The description lists the changeable field groups, which is a helpful map over 18 parameters, but adds no semantics beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("Altera um passo") and enumerates the mutable surface: image, highlight, click, texts, position, video. That distinguishes it from add_step/delete_step/reorder_steps even without naming them. It stops short of explicitly differentiating from the siblings by name.

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

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

"só os campos enviados" signals partial-update semantics and implies this is the tool for editing an existing step rather than adding one, but no when-to-use condition or alternative is stated explicitly. Usage is inferable rather than guided.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds meaningful behavior: immediate save with url/base64, return of mediaId, 15-minute upload URL expiry, and the curl PUT follow-up with response field media.mediaId.

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

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

Front-loads the core action and return value, then efficiently describes each mode. The curl example is compact and directly useful, with no filler content.

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

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

There is no output schema, but the description supplies the key return value (mediaId or media.mediaId) and explains all invocation paths. An agent has enough information to call the tool correctly across url, base64, and local-file workflows.

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 important mode-selection semantics: providing url or base64 saves immediately, while omitting both returns an upload URL. It also clarifies that url must be https, though the optional name parameter is not discussed.

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

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

States a specific verb and resource: saves a capture in the account and returns mediaId. The three invocation modes are clearly within scope, and no sibling tool overlaps with media upload.

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 explains when to pass url, when to pass base64, and that no arguments returns a 15-minute upload URL for local files. It does not compare against sibling tools, but those are tour/step operations, so alternative guidance is largely unnecessary.

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