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

The description adds significant context beyond annotations: partial update behavior ('Só os campos enviados são alterados'), media exclusion, and a side-effect warning about the approval flow. These are not present in the annotations, making the description highly informative.

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

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

The description is concise and front-loaded, beginning with 'ESCRITA' and a clear verb. Each sentence provides essential information: fields, partial update, media exclusion, and a warning.

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 core functionality, edge cases (media untouched), and side effects (approval flow). Combined with schema descriptions and annotations, it provides sufficient context for a tool with no output schema. It could mention prerequisites like post_id existence, but the schema already covers that.

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 description complements the schema by explaining partial update semantics, clarifying that only provided fields are changed. The schema already documents formats and replacement behavior for 'roteiro', so the description adds value without redundancy.

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

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

The description clearly states 'Altera campos de texto de um post existente' (changes text fields of an existing post), listing specific fields. This distinguishes it from siblings like 'criar_post' and 'consultar_post'.

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 for editing existing posts and explicitly notes 'Não toca em mídia' (doesn't touch media), providing an exclusion. However, it does not explicitly name alternative tools for media or creation, so guidance is clear but not exhaustive.

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 readOnlyHint annotation already declares the read-only nature, and the description redundantly states 'Somente leitura'. It adds the list of returned fields, which is useful context, but doesn't disclose other behavioral aspects like error handling or pagination (not applicable here).

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

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

The description is a single, efficient sentence that front-loads the core purpose and lists key return fields without any fluff or repetition.

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

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

For a simple read tool with one parameter, the description is sufficiently complete: it lists the return fields, and the schema explains where the post_id comes from. No output schema exists, but the field list compensates. Sibling tool context is not explicitly addressed, but the tool's scope is clear.

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 post_id fully described as the UUID returned by listing tools. The description adds no additional parameter information, so it meets the baseline for high schema coverage.

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

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

The description clearly states the verb 'Consulta' and the target resource 'post específico', and enumerates the fields returned (título, legenda, roteiro, datas, mídia, status de aprovação). This distinguishes it from sibling tools like listar_posts_cliente (listing) and criar_post/atualizar_post (write operations).

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

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

The phrase 'post específico' implies this tool is for fetching a single post by ID, contrasting with listing tools. It provides clear context for when to use it, though it doesn't explicitly name alternatives or 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 and openWorldHint, but the description adds the specific side-effect disclosure of 'sem disparar download nem upload' (without triggering download or upload), which is more precise. No contradiction noted.

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

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

Two sentences, front-loaded with 'Somente leitura,' then purpose, then usage guidance. Every sentence earns its place with no padding.

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

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

For a single-parameter read-only tool with no output schema, the description fully covers purpose, return hints (name, attachments, linked post), and usage context. It is self-sufficient for an agent to select and 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 coverage is 100% for the single parameter, with the schema already defining clickup_task_id as 'ID da tarefa no ClickUp.' The description adds no additional parameter semantics, so baseline 3 applies.

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

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

The description clearly states the tool reads a ClickUp task and lists exactly what it inspects: name, available attachments, and linked PostGrowth post. This distinguishes it from siblings like subir_midia_clickup which performs uploads.

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 instructs to ALWAYS use this tool before subir_midia_clickup, with the rationale of checking the link and client without triggering download/upload. This provides direct when-to-use guidance and names the 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?

Beyond the annotations, the description discloses that PostGrowth automatically creates a corresponding ClickUp task that is not deleted even if the post is deleted, which is a critical side effect. It also states that approval status is derived and cannot be sent, adding behavioral constraints not present in 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?

Each sentence in the description serves a purpose: category, function, side effect, usage warning, and constraint. It is front-loaded with the core action and remains under 5 sentences, though the 'ESCRITA.' prefix adds marginal 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?

The description covers the key side effect and approval status constraint, which is important context for a create operation. It does not describe the return value, but the absence of an output schema and presence of openWorldHint soften this gap; still, the description could mention what the caller receives.

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

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

The input schema has 100% description coverage for all 7 parameters, so the schema already handles parameter semantics. The description adds little beyond reinforcing that the post is text-only; no additional parameter-level details are provided.

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 'ESCRITA' and states 'Cria um post de texto no PostGrowth (sem arte),' clearly identifying the action and resource. The parenthetical '(sem arte)' distinguishes it from media-upload tools like subir_midia_clickup, and the create/update contrast with atualizar_post is evident.

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

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

The description explicitly warns 'Não use para testes' and instructs 'Confirme com a pessoa antes de criar,' providing clear when-not usage. It does not name sibling tools as alternatives, but the context of creating a text post versus media is 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, but the description reinforces with "Somente leitura" and adds a valuable security guarantee: "Nunca devolve tokens nem credenciais do cliente." It also reveals that the primary output is the client_id, which is beyond the schema. This is useful behavioral context not present in annotations.

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

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

The description is three short sentences, front-loaded with the main action. Every sentence adds value: purpose, read-only confirmation, usage guidance, and security note. No redundancy or fluff.

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

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

For a simple read-only list tool with one optional parameter, the description covers the key aspects: what it lists, read-only nature, usage as first step, and security limitation. It does not describe the return format, but the absence of an output schema is mitigated by the stated purpose of discovering client_id. It is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100% (the 'busca' parameter is fully documented). The description only restates the filter behavior ('filtrando por nome') already in the schema. With full coverage, baseline 3 is appropriate; no extra syntax or format details are needed.

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

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

The description states the exact action: "Lista os clientes cadastrados no PostGrowth" (lists registered clients), and adds optional name filtering. It distinguishes from siblings by explicitly positioning it as the prerequisite for other tools: "Use para descobrir o cliente_id antes de qualquer outra ferramenta."

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

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

Provides clear when-to-use guidance: "Use para descobrir o cliente_id antes de qualquer outra ferramenta." It tells the agent this is the first step before using any other tool, and the filtering behavior is also specified. Alternatives are not needed because this is the entry point.

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

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

Annotations already declare readOnlyHint=true, and the description mirrors this with 'Somente leitura', adding no contradiction. It also adds context about the returned data (approval statuses) and the prerequisite for client_id. However, it does not disclose other behavioral traits such as pagination or filtering, so the added value beyond annotations is limited.

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

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

The description is concise, consisting of two sentences. The first sentence states the primary purpose and key output fields, and the second adds the read-only qualifier and the prerequisite. Every sentence contributes directly to understanding the tool without any redundancy.

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

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

For a simple list tool with one parameter and no output schema, the description is sufficient. It covers the tool's purpose, the type of data returned, and the required input context. It could mention the return structure more explicitly, but the mention of approval statuses provides a good indication of what is returned.

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

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

The schema has 100% description coverage for the single parameter 'cliente_id', specifying it as a UUID exactly as returned by listing tools. The description's mention of obtaining it from 'listar_clientes' adds no extra semantic value beyond the schema. The baseline of 3 applies since schema fully covers parameter meaning.

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

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

The description clearly states the tool's function: listing a client's posts with approval statuses for text and design. The verb 'Lista' (lists) is specific, and the resource 'posts de um cliente' is well-defined. It also distinguishes itself from sibling tools like 'criar_post' and 'atualizar_post' by focusing on listing, and from 'consultar_post' by indicating a per-client scope.

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

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

The description provides a clear usage prerequisite: it requires a client_id obtained from 'listar_clientes'. This implies a sequencing context. However, it does not explicitly mention when not to use this tool versus alternatives like 'consultar_post', so it stops short of a full exclusionary guideline.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses that the action is irreversible, permanently deletes existing media when confirmed, cannot be undone, and affects the client-visible public approval page. It also clarifies that all writes replace the entire set, not additively.

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 lengthy but every sentence carries essential risk warnings or operational rules. It is well-structured with numbered usage rules, front-loaded with a danger warning, and avoids redundancy. The length is appropriate for a destructive tool.

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

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

The tool is a destructive mutation with no output schema, but the description covers prerequisites, behavior, side effects, error conditions (refusal when existing media and confirmar_substituicao=false), and prohibitions. The only omission is the return format, but that is not necessary for correct selection and 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?

While schema coverage is 100%, the description adds critical semantic guidance: cliente_id is a safeguard validated against the task, clickup_task_id is the source of attachments, and confirmar_substituicao is explained with its default and the condition for true (authorization to delete). This is more detailed than the schema descriptions.

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

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

The description specifies a concrete action: downloads ClickUp task attachments and uploads them to the ROI SENSEI media library via PostGrowth. It clearly distinguishes this from sibling read tools like consultar_tarefa_clickup, which is referenced as a prerequisite. The verb and resource are explicit.

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

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

The description provides explicit usage rules: run consultar_tarefa_clickup first, obtain explicit human confirmation, only use confirmar_substituicao=true with explicit authorization, and never batch. It also mentions that posts with existing media are refused unless confirmation is given, marking when to use the parameter.

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