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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the file is copied to <home>/artifacts, has a 100 MB limit, returns attachment metadata, and warns to use only user-indicated paths. However, it omits permissions, overwrite behavior, and error handling 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 compact and front-loaded with the core action, followed by use case, return value, example, and notes. Every section is short and contributes directly to invocation clarity.

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 output schema exists, so return-value details are supplementary, and the description covers purpose, usage, size limit, and an example. However, with 0% schema description coverage and no annotations, the missing connection_id semantics and lack of permission or failure behavior leave meaningful 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 0%, so the description must compensate. It gives an example showing item_id and file_path, and implies item_id links to an item while file_path is a local path, but the optional connection_id parameter is never explained or mentioned.

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: attaching a local file to an item, with copy destination and size limit. This clearly distinguishes the tool from sibling artifact_get and from unrelated item 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?

It explicitly says when to use the tool: when the item value is a file such as a diagram, template, or script. It also points to item_get for listing existing artifacts, though it does not state when not to use this tool or name a direct 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?

No annotations are provided, so the description carries full behavioral burden. It usefully discloses that the payload is base64 and implicitly warns about size by telling the agent to confirm file_size first, but it says nothing about size limits, token/memory cost, or auth requirements for reaching the blob.

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 return payload, then use-case, then example — tight and scannable with no filler. The 'Retorna' line partially duplicates the existing output schema, but it costs little and aids fast reading.

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

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

An output schema exists, so return values needn't be spelled out, and the item_get cross-reference covers the main workflow. However, for a 2-param tool the undocumented connection_id and absent guidance on large/failed fetches leave real 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 0% for both parameters. The example shows artifact_id in use but never explains where it comes from or what it identifies, and connection_id is entirely undocumented in both schema and description, so the description fails to compensate for the coverage gap.

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

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

States the resource and the exact payload ('Conteúdo de um anexo em base64'), which is a specific verb-free but unambiguous purpose. It distinguishes itself from item_get by noting that item_get is where you check file_size before fetching the artifact itself, so an agent can route between 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?

'Use quando: Precisar do arquivo em si' gives an explicit trigger condition and names the alternative (item_get / file_size) as a prerequisite check. No explicit when-not case, but the context is clear enough to select correctly.

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

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

With no annotations, the description carries full behavioral burden. It usefully discloses the artifact location (ZIP in <home>/exports) and the restore caveat about new ids, but says nothing about permissions, whether an existing export is overwritten, or failure modes for a missing workspace.

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?

Bold-labeled sections (Use when / Returns / Example / Notes) are front-loaded and scannable, each carrying distinct information with no filler.

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

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

An output schema exists, so omitting deeper return-value detail is acceptable, and usage plus the sibling pointer are covered. The remaining gap is the undocumented connection_id, which an agent may need to supply.

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 compensate. It clarifies workspace and domain through the parenthetical and two concrete examples, but connection_id is never mentioned or explained anywhere, leaving one of three parameters semantically 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?

States a specific verb+resource (export a workspace or a domain to a ZIP), specifies the output location (<home>/exports), and distinguishes itself from the sibling backup_import, which it names as the reverse 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?

Provides an explicit 'Use when' clause (before big changes, or to move knowledge to another machine) and routes restoration to backup_import. It lacks an explicit 'do not use for X' exclusion, but the context and the named alternative make selection unambiguous.

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

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

With no annotations, the description must carry the behavioral burden. It discloses an important failure mode (existing workspace name rejected) and a safety constraint (only user-indicated paths), plus the success return shape, but says nothing about whether an import overwrites/merges existing domains, permission requirements, or size/time limits.

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?

Labeled sections (purpose, Use quando, Retorna, Exemplo, Notas) with the core statement front-loaded and no filler. Every line adds either routing, constraint, or example value.

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

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

Covers purpose, usage trigger, return shape, a concrete call example, and key constraints, which is strong for a 3-param mutation tool. The return values are also covered by an output schema, so the main remaining gap is the undocumented connection_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 description coverage is 0%, so the description must compensate. It explains file_path (a ZIP produced by backup_export) and workspace (the domain inside the workspace), which meaningfully supplements the bare string types, but connection_id is never mentioned and the workspace/null semantics remain ambiguous.

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 (import a ZIP) and names the counterpart sibling backup_export as the source of the artifact, so the agent immediately understands the inverse relationship. It further scopes the outcome to either a whole workspace or a domain inside a workspace.

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 when-to-use line: restoring a backup or bringing knowledge from another machine. It lacks a formal when-not/alternative clause, but the 'Notes' section adds a hard exclusion (existing workspace name is refused) and a constraint (only user-indicated paths), which covers most of the routing need.

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?

No annotations exist, so the description carries the full behavioral burden and largely meets it: it discloses the `budget_tokens` cap, that path/query matches arrive focused with the start of content while the rest show only title/summary/key, how `sensitive` is set, and which scopes are included/excluded (substituted, obsolete and ephemeral items omitted). Permissions and performance characteristics are the main gaps.

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?

Well front-loaded with bold section headers (Use quando / Retorna / Exemplo / Notas) that let an agent skim. The 'Retorna' field list duplicates what the existing output schema already specifies, which is the only wasted line; the rest is dense and 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 5-parameter tool with 0% schema description coverage and no annotations, the description supplies the usage triggers, scoping semantics, budget behavior and inclusion/exclusion rules an agent needs to call it correctly. With an output schema present, the explicit return-field listing is redundant, and `connection_id` remains undocumented, but overall it is nearly complete.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for most parameters: `paths` (scoped rules for those files), `query` (related items), `project` (shown as project=".") and `budget_tokens` (results capped within it) all gain meaning. Only `connection_id` is left unexplained 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 resource clearly: a project context bundle covering rules, context, decisions, patterns and procedures. The retrieval verb is only implicit ('context_get') and no sibling is named directly, though the note that focused items 'dispensa item_get' hints at the item_get overlap. Clear but not fully differentiated from item_get/item_search in the purpose line itself.

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 '**Use quando:**' block gives explicit triggering conditions: starting on a project (when the hook hasn't injected) or moving into another area, with `paths` for scoped rules and `query` for related items. It covers when to reach for this tool but does not lay out explicit when-not rules beyond the hook 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?

With no annotations present, the description carries the full burden and largely meets it: it discloses what is validated (connection plus presence of all tables, including the full-text search table) and the shape of the response. It stops short of explicitly stating there are no side effects or auth requirements, but for a zero-param health probe the behavioral surface is well covered.

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?

Bold-labeled sections (Use quando / Retorna / Exemplo / Notas) front-load the purpose and keep the reader oriented. The example line is near-redundant for a no-argument tool and the Retorna fields partly duplicate the existing output schema, costing a little efficiency.

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

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

An output schema exists, so return values need not be described, yet the description still enumerates the return fields (status, database, version, schema_version, toolset) and the validation notes. For a zero-parameter diagnostic tool this leaves nothing an agent needs unresolved.

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 per the rubric the baseline is 4. The description's 'Exemplo: health_check()' correctly reinforces that no arguments are accepted, consistent with the empty 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+resource combination ('Verifica a saúde do servidor MCP e do banco default') that is unambiguous and distinguishable from every sibling, none of which are diagnostic tools. An agent immediately understands this reports server/database health.

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?

'Use quando: Diagnosticar falhas ou confirmar que o servidor está operacional' gives explicit when-to-use conditions. There is no sibling alternative to route against, so no exclusion is needed, but the guidance is clear rather than 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?

No annotations exist, so the description carries the full load and does so well: it declares the operation destructive, permanent, and enumerates the collateral scope (tags, relations, attachments). It does not cover authorization/connection scoping, which keeps it short of a 5.

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

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

The destructive action and its scope are front-loaded in the first sentence, followed by clearly labeled Use quando / Retorna / Exemplo / Notas sections. Every line carries information and there is no filler.

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

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

An output schema exists, and the description still names the return shape; destruction scope, routing alternative, and usage condition are all covered for a simple 2-parameter delete. The unresolved connection_id semantics is the only real 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 description coverage is 0% across 2 parameters, so the description must compensate. It only shows item_id inside an example string and says nothing about connection_id, leaving half the parameters 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+resource (remove/delete an item) and precisely scopes what is removed: tags, relations and attachments. Marks it as destructive, which immediately distinguishes it from the retire-with-history path offered by item_save.

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?

Contains an explicit 'Use quando' clause (item is wrong and no history needs preserving) plus a 'Notas' section naming the alternative (item_save with status=deprecated or a supersedes relation) and the condition that selects it. When-to-use, when-not, and the alternative are all present.

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

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

With no annotations, the description carries the burden and mostly does: it discloses graceful degradation (missing items returned as {key|id, missing: true} without failing others), the batching limit (up to 20 per call), and ordering guarantees. It omits any auth/permission or addressee-side effects, but the batch and partial-failure semantics are genuinely useful.

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

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

Front-loaded verb phrase followed by clearly labeled sections (Use quando, Retorna, Exemplo, Notas). Every line carries usable information with no filler, and the concrete example grounds the wire format.

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 6-param, zero-schema-coverage tool the description covers the critical operational facts: batch limit, key-addressing prerequisites, and missing-item handling. An output schema exists so return-shape docs are a bonus rather than required; only the unlabeled ids/domain/connection_id semantics remain a 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 0% across 6 params, so the description must compensate. It clarifies the keys/project/workspace/domain relationship ('keys exigem project... ou workspace e domain') and id/key dual addressing, but leaves 'ids', 'domain', and 'connection_id' uninterpreted, so coverage is partial rather than complete.

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 ('Lê') and resource ('itens completos') with an explicit scope enumeration (content, tags, relations, attachments) and distinguishes itself from the search/context summary path that returns less. An agent can tell it apart from item_search 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?

Has an explicit 'Use quando' block naming the trigger condition (search/context summary was insufficient), which effectively routes away from item_search and context_get. However, it does not name those alternatives explicitly or state when NOT to use it.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: batch is transactional (one error rolls back the lot and points at the offending entry), secret-like content is refused, secrets store no value and return a fill_url for the user to complete in the local UI, and similar-title detection fires on creation. This is exactly the operational context an agent needs before writing.

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?

It is long, but the bold labels (Use quando / Retorna / Modo / Exemplo / Campos / Segredo / Notas) front-load the mode decision and the examples each demonstrate a distinct operation rather than restating one. Dense yet every block earns its place for a tool with this many modes; slightly heavy for quick scanning.

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

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

An output schema exists, yet the description still summarizes the return shape and, more importantly, covers the failure paths (rollback, refused secrets, rejected secret-like content) and the secret-filling workflow. Combined with the schema, an agent has everything needed to call this correctly on the first attempt.

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 compensate — and it largely does, documenting the per-item mode switch (key → upsert in domain, id → update, neither → create + similar), the full field list (type, status, relations, scope_paths, memory_class/ttl_days, workspace/domain), and the project/domain fallback. Only connection_id is left 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?

The opening line states a specific verb and resource ("Grava itens") and enumerates the write modes it covers (criar, atualizar, upsert, renovar, relacionar) inside a transaction, so an agent immediately knows this is the write path. It never names the read/delete siblings (item_get, item_search, item_delete), but the semantics make the boundary obvious.

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?

"Use quando" gives concrete triggering situations — persisting a user-stated rule, decisions/learnings from a completed change, a correction to an item. It gives no explicit when-not or named alternative (e.g. use item_search to look things up, item_delete to remove), so the negative space 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?

No annotations are provided, so the description carries the full burden, and it does disclose real behavior: returns summaries not full content, default project/workspace scoping with no cross-project leakage, everywhere=True for global search, relevance-first ranking, accent/plural tolerance, and include_inactive surfacing superseded/obsolete/expired ephemeral items. It stops short of stating read-only guarantees or pagination/rate behavior, but the behavioral disclosure is rich.

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, then bolded Use/Returns/Example/Notes sections that scan quickly. Slightly dense in the Notes paragraph but no redundant filler.

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

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

For a 10-parameter tool with zero schema coverage and no annotations, several filters (types, domain, memory_classes, connection_id) remain undocumented. The return-field list is redundant given an output schema exists, while the genuinely useful undocumented parameters are not covered, leaving the definition only partially complete.

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

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

Schema description coverage is 0% across 10 parameters, yet the description explains the semantics of key ones: project/workspace defaulting, everywhere, include_inactive, and query/limit (with a limit=5 example). It leaves types, domain, memory_classes, and connection_id completely unexplained, so it only partly compensates for the coverage gap.

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 clear verb+resource (text search over stored items) and immediately draws a boundary relative to the sibling item_get by saying it "devolve resumos, nunca o conteúdo completo." An agent can tell it is a search/retrieval tool and not a fetch-full-content tool, though item_get is never named explicitly.

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

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

The "Use quando" block gives a concrete trigger (looking for something that may already be stored: decision, gotcha, procedure). It does not name alternatives or explicit exclusions, but the summary-only constraint implicitly routes full-content needs elsewhere.

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?

No annotations are provided, so the description carries the full disclosure burden. It usefully states that workspace and domain are created if absent and that relinking moves the project, but omits permissions, idempotency, and other side effects expected of a mutation tool.

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

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

Uses bold headings and front-loads purpose and usage. It includes a return shape even though an output schema exists, which is redundant, but the overall structure is efficient and every other section adds value.

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

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

Covers purpose, usage, return, example, organization, and parameter notes, which is substantial. Yet with 0% schema coverage and no annotations, the undocumented connection_id and missing behavioral details (permissions, side effects) leave gaps for a four-parameter 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?

Schema description coverage is 0%, so the description must compensate. It fully explains project (path/URL/key, normalized git remote) and the roles/derivation of workspace and domain, but connection_id is never mentioned. Partial compensation for four 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 ('Liga') and resource ('repositório a workspace/domain do segundo cérebro'), with example and return shape. Sibling tools do not include a comparable link operation, so the purpose is unmistakable.

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

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

Gives explicit when-to-use guidance: configuring a project for the first time, and notes that /plumb-setup performs this. It does not name alternatives or when-not conditions, but the context 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?

No annotations are provided, so the description carries the full burden, and it discloses a genuinely useful side effect: removing a supersedes relation does not reactivate the target, requiring a follow-up item_save. It still omits permissions/authorization requirements and whether the deletion is reversible.

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

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

Front-loaded with the core action, then cleanly sectioned into Use quando / Retorna / Exemplo / Notas. Every line adds signal, and the example makes invocation concrete with no wasted prose.

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 tool with an output schema already covering the return value, the description covers purpose, trigger, provenance, and the supersedes caveat. The remaining gap is the undocumented connection_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 description coverage is 0%, so the description must compensate. It explains the provenance of relation_id and gives a usage example, but the optional connection_id parameter is never mentioned, leaving half the parameters undocumented.

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 (remove) and resource (a relation between items), and adds where the identifier comes from ('o id vem em item_get → relations'). This clearly distinguishes it from sibling delete tools like item_delete and structure_delete, which operate on different resources.

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 'Use quando' section gives an explicit trigger ('Uma relação foi criada por engano'). However, it offers no exclusions or named alternatives for other cleanup scenarios, and the interaction with item_save is only hinted at in the notes.

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

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

With no annotations, the description carries the full burden and does so well: it declares the operation destructive, explains the two-phase confirm gate (without confirm = preview with would_delete; with confirm = actual deletion), and instructs calling without confirm first to show a preview. This discloses the exact safety-critical behavior of a deletion tool.

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

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

Front-loaded purpose followed by clearly labeled sections (**Use quando**, **Retorna**, **Exemplo**, **Notas**). Every line earns its place for a destructive tool, with no redundancy.

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

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

Given a destructive 4-param tool with 0% schema coverage and an output schema present, the description covers purpose, invocation trigger, return behavior, an example, and safer alternatives. The only real gap is the undocumented 'connection_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 description coverage is 0%, so the description must compensate. It fully explains 'confirm' semantics and demonstrates 'workspace' via the example, and implies 'domain' scope, but 'connection_id' is never mentioned. Partial coverage of a 4-param schema that is otherwise undocumented.

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 (Remove) plus the exact resource and scope ('um domain ou o workspace inteiro com todos os itens'), which clearly separates it from item_delete and relation_delete siblings. The word 'Destrutivo' is front-loaded so an agent can immediately gauge severity.

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 scopes invocation to 'O usuário pediu explicitamente para apagar' and names alternatives with their conditions: prefer backup_export beforehand and use status=deprecated via item_save when historical data matters. This is genuine when/when-not/alternative 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?

With no annotations, the description carries the full behavioral burden. It discloses the return shape and the boundary that creation happens elsewhere, but never states that this is a non-destructive read, what connection_id selects, whether results are paginated or auth-scoped. Adequate but with real gaps for a zero-annotation tool.

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

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

Front-loaded one-line summary followed by labeled Use/Returns/Example/Notes blocks. Dense but every line adds information; nothing is redundant 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?

An output schema exists, so return-value explanation is not strictly required, and the tool has only two optional params. Still, connection_id is undocumented in both schema and description, and the read-only nature is left implicit for a tool with no annotations.

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. The example structure_list(workspace="agenda-api") shows the workspace param is a name filter and that omitting it returns everything, but connection_id is never explained anywhere. Partial compensation only.

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 (the workspace → domain tree) and its payload (item counts), so an agent immediately knows this is a structural overview, not an item fetch. It also explicitly distinguishes itself from siblings by noting that workspace/domain creation lives in item_save and project_link rather than here.

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?

"Use quando" gives concrete triggers: before organizing, before project_link, before backup_export. It also draws a boundary by saying creation is not done here. No explicit when-not or named alternative for the inverse case, but the context 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?

With no annotations, the description carries the whole burden. It discloses the return shape per action ('list → [{id, name}]', 'create → {id, name}', 'delete → {status: deleted}') and the tags-vs-labels distinction, which is genuinely useful. It omits permission/auth requirements and, importantly, does not say what deleting a label does to items already carrying it — a real gap for a destructive action.

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?

Labelled sections (Use quando / Retorna / Exemplo / Notas) front-load the trigger and pack parameters, returns, and an example into four short blocks. Dense and readable with very little filler; slightly compressed syntax but nothing 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 5-parameter, no-required, multi-action tool with 0% schema coverage and no output schema, the description supplies the missing action model and per-action return shapes. Only 'connection_id' and the exact effect of delete on existing item tags are unaccounted for.

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, and it largely does: it defines the allowed values of kind ('tags | labels'), the action set and the argument each action takes ('create (name)', 'delete (id)'). Only 'connection_id' is left unexplained, and the enums remain informal rather than schema-enforced.

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 opening line names the resource precisely ('tags (livres)' vs 'labels (lista controlada)') and the actions surface in the example and notes (list/create/delete). An agent can tell it deals with the tag/label vocabulary rather than items or structures. It stops short of an explicit verb+resource sentence up front and does not name the sibling it is distinct from.

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 'Use quando' line gives a concrete trigger (reuse existing tags before creating variants; manage labels), and the closing note routes the agent to item_save for the overlapping case of creating tags on an item. Clear context, but no explicit when-not-to-use beyond that one overlap.

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