HOC Guard MCP

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, but the description goes well beyond them: it discloses that code is read locally and nothing leaves the machine, that no files are altered, and that the output is a ConsentField component plus the insertion location. This is exactly the behavioral context the annotations cannot convey.

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

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

Three sentences, front-loaded with the purpose, then method, then output and the no-mutation caveat. Every sentence carries weight, though the parenthetical field list is slightly dense.

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

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

The description communicates the input method (local read), the returned artifact (ConsentField with legal basis and policy link plus insertion point), and non-mutation, which compensates for the absent output schema. However, the two undocumented parameters remain a real gap for a tool an agent must invoke 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 0% and the description never mentions the two parameters (files with path/content, and project_path). It only alludes to reading local code, leaving the agent to infer the meaning and format of both inputs from the schema alone.

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

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

States a specific verb+resource: adding an LGPD consent collection point to forms in a Next.js project that collect personal data (e-mail, telefone, CPF, nome). This scoping to Next.js forms distinguishes it from siblings like guard_generate_cookie_banner and guard_generate_policy at a glance.

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 context for use (Next.js projects with forms collecting personal data) but never states when to choose this over sibling tools such as guard_make_compliant or guard_check_compliance. No explicit alternatives or exclusions are given, so routing relies on inference.

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

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

Annotations already flag destructive=true and idempotent=false, and the description adds substantial context beyond them: exactly what is destroyed ('a finalidade... some' if born from the proposal and never published), what is left intact, and the auth prerequisite (guard_login with edit permission). This is precisely the extra behavioral detail the structured fields cannot carry.

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

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

Front-loaded with the action verb and the affected object; subsequent sentences are dense with scoping and auth constraints rather than filler. Slightly long, but each clause carries distinct 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?

For a single-parameter mutation with no output schema, the description covers the destructive effect, the scope limits, and the authentication requirement. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and there is a single parameter whose description ('Id da finalidade cujo rascunho será descartado') mirrors the schema text. The prose adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('desiste da proposta (rascunho)... numa finalidade'), so an agent knows this cancels a draft proposal on a purpose. It contrasts with the published version and other agents' drafts, giving scope beyond the name, though it does not explicitly name a sibling alternative like guard_update_purpose.

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

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

Provides explicit when-it-applies conditions (only the caller's own proposal, same agent and same logged-in person, unpublished) and when-not (draft open on screen, another person's/agent's draft, published version are untouched). Clear context and exclusions, though no sibling tool is named as 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 readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuine value beyond that: the privacy guarantee that nothing leaves the machine ('nada sai da máquina') and a description of the return shape (findings ordered by severity plus a 0-100 score). It stops short of disclosing pagination, limits, or how the two input modes behave.

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

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

Front-loaded with the core purpose, then what it detects, then the output, then the sibling exclusion. No filler sentences, though the enumeration of checks is slightly longer than strictly needed.

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 states what comes back (severity-ordered findings plus a 0-100 score), and annotations cover the safety profile. The main incompleteness is the input contract, which the description leaves entirely to the schema.

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

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

Schema description coverage is 0% and there are two undocumented parameters (files and project_path), yet the description only says it 'reads the code' without explaining that either a files array or a project_path can be supplied, or how they differ. The description does not compensate for the coverage gap, leaving the agent to infer the input contract from raw schema keys.

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 (local LGPD compliance check of a project's code) and enumerates the exact classes of problems it detects (non-essential trackers firing without consent, forms collecting personal data without consent, missing privacy-policy link). It also distinguishes itself from guard_scan_site, so an agent can route correctly without opening either schema.

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

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

Explicitly defines the negative case and the alternative: 'Não roda no site publicado (para isso use guard_scan_site); é uma checagem estática do código.' The when/when-not/alternative triple is fully specified.

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 mutation/openWorld/idempotency, but the description adds the concrete dedup rule ('se já existe um banner... devolve o mesmo, sem duplicar'), the data-minimization guarantee ('Não envia código: só a origem do site, as finalidades e os nomes dos serviços'), and the accountless/claimable status. That is real behavior beyond the hints, though error and rate-limit behavior is unstated.

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 what it creates and what it returns, then layers on sourcing, dedup, and data handling. Each sentence carries information, though it is dense and slightly repetitive around purposes derivation.

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?

No output schema exists, so the description usefully names the returned banner_id and where to use it, and covers auth (no account), dedup, and transmitted data. Missing only locale handling, permissions nuances, and failure modes for a mutation tool.

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

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

With only 20% schema description coverage, the description does the heavy lifting: it explains that purposes are derived from detected trackers via project_path or files, or supplied directly via purposes, and that raw code is not sent. It omits locale (the default pt-BR) and adds little on site_url beyond the schema's own description.

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

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

States a specific verb and resource ('Cria o banner de cookies do HOC Guard para um site'), the no-account condition, and the return value (banner_id). It names the siblings that consume the result (guard_generate_cookie_banner, guard_make_compliant), so an agent can distinguish this creation step from downstream steps.

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?

Clearly frames the scenario (create a banner without an account) and explains the follow-on use of the returned id, plus that the banner can be claimed after signup. It does not explicitly compare conditions under which an agent should pick this versus guard_generate_cookie_banner/guard_make_compliant, so it stops short of full when-not guidance.

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

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

Annotations only declare non-readonly, non-idempotent, non-destructive. The description goes well beyond that: nothing is published, a human reviews and clicks 'Liberar', validation rules run before submission, and the LIA phase requirements (lia_interest, lia_necessity, lia_balance, lia_opt_out) are enumerated. That is substantial 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?

Front-loaded with the mutate-draft fact and the human-approval flow, followed by preconditions and validation rules. Dense but each sentence carries distinct information; slightly long but nothing is wasted.

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

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

For a 20-parameter mutation tool with no output schema, the description covers the flow, preconditions, and conditional validation rules. Minor gaps remain (e.g., what is returned after draft creation, whether the draft is editable later), but nothing that would block 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, but the description adds conditional dependency semantics the schema only implies: legitimate_interest requires the three LIA phases plus opt-out, and consent is required when sensitive data is involved. This meaningfully exceeds the flat per-field 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?

Specific verb ('cria') plus resource ('finalidade nova na conta do Guard') plus mode ('como RASCUNHO'). It implicitly separates itself from guard_update_purpose, guard_get_purpose, and guard_list_purposes by naming the draft-creation act.

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

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

Explicit prerequisites and ordering: consult guard_list_purposes first to avoid duplicates, and requires guard_login with edit permission. It also states when a legal basis is invalid ('legítimo interesse não vale com dado sensível'), which is directly actionable guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one real behavioral fact not in the annotations: calling with no argument returns a list of available codes, and output is in plain Portuguese. No detail on error handling for an invalid code.

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

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

Two sentences, zero padding. The core action and its output are front-loaded, and the no-argument fallback behavior is appended where it belongs. Every clause earns its place.

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

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

For a read-only, single-optional-param tool with no output schema, the description covers enough: it says what the return content looks like and what happens without a code. Only the invalid-code case and the language/format scope are left implicit.

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 0% and the single optional param has no schema-level documentation, so the description must carry it. It does supply a concrete example value ('tracker-sem-consentimento'), which anchors the expected format, but it does not say whether the code is required for a single-finding explanation or what happens with an unrecognized code.

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 ('Explica ... um achado de conformidade') and even enumerates the output content (what it is, why it matters, LGPD relevance, remediation). It is clearly distinct from the check/scan/generate siblings, though it never names an alternative tool to reinforce the separation.

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 stated: call it with a finding_code to explain one finding, or with no argument to discover available codes. That implicit hint is useful, but there is no explicit 'use this instead of X' guidance and no mention of when an explanation is warranted versus re-running a check.

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 annotations: it states nothing leaves the machine, that it does not alter files and that returned changes must be applied by the caller (consistent with readOnlyHint/idempotentHint), lists the specific trackers detected, and describes both output modes. This is rich, actionable 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?

The description is fairly long but front-loads purpose, then mode logic, then parameter guidance, and every sentence carries information about behavior or invocation. Slightly verbose but 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?

With no output schema and 0% parameter coverage, the description compensates by describing what is returned in each mode and how to invoke it. The only gap is the unexplained banner_id parameter.

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 0%, so the description must carry parameter meaning. It does explain project_path (project root) and files (code not yet saved), which is useful, but never mentions banner_id, leaving one of three parameters undocumented in both schema and description.

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

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

States a specific verb and resource: it generates cookie-consent compliance output for a Next.js project under LGPD, locally scanning code to detect trackers. The two possible outputs (consent-gate banner vs. notice) are named explicitly, so an agent knows exactly what this returns.

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

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

It explains the internal decision logic between consent-gate and notice modes and tells the user to supply either project_path or files, which implies when the tool applies. However, it never distinguishes this from siblings like guard_create_banner or guard_generate_policy, so selection guidance 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 readOnlyHint=true, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond that: it reads locally, sends nothing off the machine, and returns Markdown. It does not detail file handling or authentication needs, but the local-only behavior is a valuable 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 four sentences, front-loaded with the core action, and every sentence adds distinct value: non-generic nature, local execution, return format, and accepted parameters. There is no redundant or 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?

The description covers the tool's purpose, local execution, and output format, which is adequate given the annotations already declare its read-only and non-destructive nature. However, with no output schema and zero schema parameter descriptions, the definition should clarify how files and project_path interact and whether input is provided directly or via a path, leaving a clear gap 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 description coverage is 0%, so the description must compensate. It names only three of five parameters (site_name, controller_name, dpo_email) and their broad purpose, leaving files (a nested array) and project_path completely unexplained. This is insufficient for a tool with five undocumented parameters.

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

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

States a specific verb and resource ('Gera um rascunho de política de privacidade') and clarifies it is not a generic template, which distinguishes it from generic generators. However, it does not explicitly differentiate itself from sibling tools such as guard_generate_cookie_banner or guard_make_compliant.

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?

No guidance is given on when to use this tool versus alternatives, nor are prerequisites stated (e.g., whether a scan must happen first). The description implies its purpose but leaves usage conditions entirely to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds real value: it discloses the auth requirement and that the response includes a draft alongside the published version plus derived "pendências óbvias" warnings, which the agent cannot learn from 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?

A single front-loaded sentence with the action first and the field inventory after; the enumeration is dense but every item describes an actual returned field, so it 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 no output schema, the description carries the burden of describing returns, and it does so thoroughly (fields, versions, draft, derived warnings) while also noting the login prerequisite. A minor gap is the absence of error behavior for an invalid or missing 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?

Schema coverage is 100% and the schema already explains the single id parameter including its origin (guard_list_purposes). The description adds no further meaning about the id beyond what the schema provides, so the baseline 3 applies.

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

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

Starts with a specific verb+resource ("Mostra uma finalidade da conta do Guard") and enumerates the exact fields returned, so an agent can see this is a single-purpose read that yields a formatted detail view, distinct from the list-style sibling guard_list_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?

States the prerequisite "Exige guard_login", which is useful routing context. However, it never says when to prefer this over guard_list_purposes or guard_explain, leaving the when-to-use decision to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that: results are ordered most-severe to least-severe, an overall score is included, and passed checks are hidden by default — genuinely useful traits not derivable from 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?

Two tight sentences, zero filler, with the core behavior (findings + ordering + score) front-loaded and the optional-parameter caveat second. Nothing is repeated from the name 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?

There is no output schema, so the description must describe the return value — and it does: a severity-ordered findings list plus an overall score, filtered by default. The remaining gap is the limit parameter's effect on the returned set, which is not addressed anywhere.

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 0% for all three parameters, so the description must carry the load. It explains include_passed clearly (show passing checks too), but says nothing about scan_id (which scan / where it comes from) or limit (whether it truncates the findings list or paginates), leaving two of three parameters undocumented anywhere.

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 returns the findings of a completed scan — and adds scope details (severity-descending ordering, overall score). It implicitly separates itself from guard_get_scan_status by requiring a 'varredura concluída', but never names the sibling or states the precondition 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?

It gives usable guidance for one parameter ('passe include_passed para ver também o que está correto'), which tells the agent the default view is filtered to problems only. However, it never says when to call this versus guard_get_scan_status, nor what happens if the scan is not yet finished.

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, so the safety profile is covered. The description adds real value on top: it enumerates the four possible return states and warns that repeated polling should be spaced out, which is behavioral guidance not present in the 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?

Three short sentences with no filler: purpose first, then the possible outcomes, then the polling caveat. Every sentence earns its place and the key 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 no output schema, the description does the necessary work of listing the status values an agent will receive. It is missing only what happens after 'completed' (whether results are immediately fetchable via guard_get_scan_results) and any failure-recovery hint.

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?

Only one parameter (scan_id) with 0% schema description coverage, so the description carries the burden. It implies the ID originates from guard_scan_site, which gives useful provenance, but never states the expected format or that it must be the identifier returned by the scan call.

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 ('informa em que pé está uma varredura') and scopes it to scans initiated by guard_scan_site, which cleanly separates it from guard_get_scan_results. It stops short of naming the results sibling explicitly, so an agent must infer the status-vs-results split.

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

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

Gives clear usage context: call it for a scan started by guard_scan_site and poll with a delay ('Espere alguns segundos entre consultas'). No explicit when-not-to-use or named alternative (e.g. guard_get_scan_results) is offered, so it is context without exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it discloses the auth prerequisite (guard_login) and enumerates the three possible states each returned purpose can be in, which shapes how the agent interprets results.

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

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

Three sentences, front-loaded with the resource and scope, then usage, then prerequisite. Tight and free of filler; the parenthetical gloss on "finalidades" is the only near-redundant element but aids comprehension.

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 list tool with no output schema, the description covers what is returned (purposes with their states), when to call it, and the auth requirement. Pagination and filter behavior are left to the schema, which is acceptable since no output schema exists but the state model is the key missing piece and it is explained.

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 60% and the status enum is already documented in the schema, so the description's listing of published/draft/agent-proposal states largely mirrors structured data. The filters (search, legal_basis, page, per_page) get no added meaning in the description. 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 ("Lista") and resource ("finalidades de tratamento de dados da conta do HOC Guard"), and even defines the concept parenthetically ("por que a empresa usa cada dado pessoal"). Clearly distinguishable from siblings guard_get_purpose (singular), guard_create_purpose, and guard_update_purpose.

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

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

Explicitly says when to use it: "Use antes de criar uma finalidade, para não duplicar." It also names the prerequisite ("Exige guard_login"). The alternative (guard_create_purpose) is implied by the dedup rationale, giving an agent a clear routing rule.

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

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

Annotations already declare openWorldHint=true and idempotentHint=false, so the bar is lower. The description adds real substance beyond that: the call returns a link and short code immediately without blocking, completion is deferred to a second tool, and the resulting token is scoped by account role. It does not say where the token is stored or whether it expires, which keeps this from 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 sentences, each load-bearing: what the tool does and its style, what it returns and what the user must do, and the follow-up call plus run-once-per-machine rule. The critical immediate-return behavior 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?

There is no output schema, so the description must carry return-value semantics, and it does — an immediate link plus short code, with the authorization step delegated to guard_login_check. Combined with the sibling hand-off and reuse note, an agent has everything needed to drive the flow 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% with a single optional 'scope' parameter whose default and meaning are fully documented in the schema. The description adds no additional syntax or format guidance for scope, 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 and resource in plain terms ('Começa o login no HOC Guard') and immediately anchors it to familiar analogues (npm login / gh auth login). It is clearly distinguishable from siblings guard_login_check (step 2) and guard_logout, which the description names or implies.

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

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

Explicit sequencing: run this first, show the user the link/code, wait for browser authorization, then call guard_login_check to complete. It also states the frequency constraint ('uma vez por máquina') and that downstream tools (guard_scan_site, generators, purposes) reuse the session automatically, so the agent knows when NOT to call it again.

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?

It discloses a real side effect beyond the annotations: on success it saves the credential and returns "Conectado", while on failure it only warns and requires a retry. This explains the non-idempotent, non-read-only nature declared in annotations by describing the credential-saving write and the pending-state behavior.

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

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

A single tight sentence-pair that front-loads the core purpose (completing the guard_login flow) before the success and retry branches. Every clause carries meaning, though the phrasing is slightly 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?

With no parameters and no output schema, the description supplies what an agent needs: what triggers the call, what the two possible outcomes are, and the retry rule. Annotations cover the safety profile, so nothing critical is missing, though a note on the required prior browser authorization state could be more explicit.

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 and the description correctly introduces none; 0-param tools baseline at 4. No syntax or format details are needed because there is no input to describe.

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 concludes the login started by guard_login, explicitly framing itself as step 2 of a two-step flow. It clearly distinguishes itself from the sibling guard_login, which an agent can select apart without opening either schema.

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

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

It gives clear sequencing context: run this after guard_login, and if the user has not yet authorized in the browser, re-run it after they do. The dependency on the sibling tool is explicit, though it does not enumerate when-not-to-use relative to other siblings like guard_logout.

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

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

Annotations cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description goes beyond them by naming the specific artifacts affected: the remote agent session and the local credential file path. It does not mention permission requirements, but for a zero-parameter local tool this is solid added value.

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

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

Two tight sentences with the primary action front-loaded and the downstream consequence second. 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?

With zero parameters, no output schema, and annotations already declaring the safety profile, the description supplies everything needed: what is revoked, what file is deleted, and the resulting auth state.

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

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

The tool takes no parameters, so the schema baseline of 4 applies; there is nothing further the description could clarify about inputs.

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 ('Encerra o login local do Guard') and enumerates the exact effects: revoking the server-side agent session and deleting the credential at ~/.hocguard. It is trivially distinguishable from the sibling guard_login and the scan 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?

Conveys context through consequence — 'Depois disso, varrer volta a exigir guard_login' tells the agent this ends the authenticated state and that scans will subsequently fail. It does not explicitly say when an agent should call it versus not, but the implied usage is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, and the description is consistent with them ('Não altera arquivos'). Beyond the annotations it adds real value: it reads code locally, runs the diagnostic, and returns actionable artifacts rather than performing mutations. It omits any note on auth, size limits, or runtime cost.

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

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

Four sentences, front-loaded with the outcome ('em um passo') followed by mechanics and the key non-mutation caveat. No filler, though the deliverable enumeration 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 composite analysis tool with no output schema, the description does explain the kinds of results returned (banner integration, consent points, policy draft, checklist with before/after score), which is helpful. But with 4 undocumented parameters and no mention of how inputs are provided, an agent still lacks enough to invoke it confidently.

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 0% across 4 parameters (files, banner_id, dpo_email, project_path), and the description names none of them. It alludes to banner and DPO concepts in passing but never explains what each parameter means, what project_path is relative to, or the shape of the files array, so the schema gap is not compensated.

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 plus a clear scope: it makes a Next.js project LGPD-ready and enumerates exactly what it returns (banner integration, consent points, policy draft, before/after checklist). It implies it is an aggregate of the granular siblings but never names one, so an agent must infer the distinction.

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 useful usage constraint — 'Não altera arquivos: o agente aplica as mudanças devolvidas' — which tells the agent the tool is advisory and the caller must apply changes. However, it never says when to prefer this over the granular siblings (guard_generate_cookie_banner, guard_add_consent_point, guard_generate_policy) or what prerequisites exist.

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

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

Annotations already declare readOnlyHint/openWorldHint and non-destructive semantics, so safety is covered. The description adds real behavioral context beyond them: it drives an actual browser, accepts and rejects the cookie banner, and inspects tracker firing before consent, reject effectiveness, dark patterns, and policy/contact-channel presence, plus an explicit runtime. It does not say whether scans can be run concurrently or what happens to a previous scan, but the added operational detail is substantial.

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 the scan behavior, then the return handle and follow-up chain. The middle clause listing scan checks is dense but each item adds discriminating information. Slightly longer than necessary, but no sentence is wasted.

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

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

With no output schema, the description correctly compensates by stating that it returns a scan_id and pointing to the retrieval tools, which covers the return contract. The one real gap is the undocumented 'framework' parameter; otherwise an agent has everything needed to invoke and follow up.

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 0%, so the description carries the full burden for both parameters and largely fails. The 'url' is only weakly implied by 'de um site', and the 'framework' enum (lgpd/gdpr/ccpa/all, defaulting to lgpd) is never mentioned at all, even though the legal regime materially changes what the scan looks for.

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 ('Inicia a varredura de privacidade de um site') and then enumerates exactly what the scan inspects (pre-consent trackers, reject behavior, dark patterns, policy and data-subject channel). This clearly separates it from siblings like guard_get_scan_status, which only retrieve results of a scan already started.

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 establishes the workflow role: this is the initiator, and it names the follow-up tools (guard_get_scan_status for tracking, guard_get_scan_results for the outcome). It also sets an expectation of ~2 minutes, which tells the agent not to block on it. It does not state any when-not-to-use condition, so it falls short of the top bar.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotent, non-destructive), yet the description adds substantial context on top: a draft is created from the published version if none exists, the published version stays live until released, unmentioned fields (contexts, collection points, LIA) are preserved, and concurrent drafts block agent edits. That is exactly the kind of concurrency and side-effect disclosure 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?

Front-loaded with the action and its draft semantics, then prerequisites and concurrency caveat. Dense and mostly waste-free, though the description is long and a couple of clauses (context selection, resumo explanation) 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 21-parameter mutation with no output schema, the description covers the essentials an agent needs to call it correctly: auth requirement, partial-update semantics, draft lifecycle, and the human-in-the-loop conflict rule. It does not describe the return value or what happens on validation failure, but no output schema exists and the core decision information is present.

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

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

With 21 parameters at 76% schema coverage, the schema carries most of the load, but the description adds a genuinely important semantic the schema alone does not make obvious: partial-update behavior (only send changed fields, everything else preserved). It also clarifies resumo's purpose and the law-based context selection. The remaining 20+ domain fields are left 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?

States a precise verb+resource+state: 'Edita uma finalidade existente como RASCUNHO'. It further distinguishes the flow from create_purpose and cancel_purpose_draft by explaining the published-vs-draft relationship, so an agent knows exactly which sibling to pick.

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 concrete conditions: send only changed fields, a mandatory resumo, and — critically — do not touch a purpose that already has an open draft by a human or another agent. It also names the prerequisite (guard_login with edit permission). It stops short of explicitly naming alternative tools (create_purpose, cancel_purpose_draft) for those cases.

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