UPí — upCampo

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real behavioral context by stating the return shape (most relevant articles plus an excerpt) and the escalation path to ler_artigo_ajuda. It stops short of noting result limits or ranking behavior, so it is strong but not exhaustive.

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 scope, then usage conditions, then the non-use case, then return behavior and the next step — a logical order with no filler sentences. It is dense but each clause carries routing 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 read-only search tool with a full schema and an output schema, the description supplies everything an agent needs: domain, query style, exclusions, return format and follow-up tool. Nothing material is missing.

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

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

Schema description coverage is 100% — both 'termo' and 'limite' are documented with examples, ranges and defaults in the schema itself. The description's phrasing about using the user's words or the screen name overlaps with what the schema already says, adding little beyond the baseline.

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 — searching the upCampo Help Center (support.upcampo.com.br) for usage articles — and enumerates the kinds of content covered (menu locations, field meaning, how-to, FAQ). It clearly distinguishes itself from the consultar_* family by scoping to 'how to use' questions.

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 examples in the user's own voice ('como cadastro um talhão', 'onde lanço abastecimento') and an explicit when-not: farm data questions should go to consultar_*. It also names the follow-up tool (ler_artigo_ajuda) and the argument (slug) for reading a full article.

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

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

Beyond the annotations, it discloses important transactional behavior: the batch is all-or-nothing, a rejected item prevents any write, and the response identifies which item failed and why. It also explains duplicate-name rejection, deactivation side effects, and the required confirmation workflow 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?

The description is front-loaded with the domain and key distinction, then moves through batch rules, atomicity, and confirmation. It is appropriately sized for a batch write tool, though some sentences repeat details already present in the schema.

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

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

Given the annotations and the presence of an output schema, the description covers what an agent needs: write intent, batch atomicity, include/update/deactivate modes, duplicate handling, and confirmation. No major behavioral or usage gap remains for this 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 100%, so the schema already documents the item fields and farm parameter in detail. The description largely restates the id/desativar conditions and the 50-item limit rather than adding new parameter-level meaning. The duplicate-name behavior is useful but is more behavioral than parameter semantics.

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

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

The description states a specific verb/resource by explaining that it writes product classes ('GRAVA no upCampo') and covers include/update/deactivate modes. It also distinguishes the tool from the sibling consultar_base_upcampo by clarifying that the base only suggests names while the class belongs to the client.

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 operational context: send the full list at once, use no id to include, id to alter, and id plus desativar to deactivate. It also instructs the agent to show the user the list and confirm before calling. It lacks an explicit when-not-to-use statement, but the alternatives and conditions are otherwise 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 only flag a non-idempotent, non-destructive write. The description adds high-value behavior beyond that: the all-or-nothing transaction ('se um item for recusado, NENHUM é gravado'), the duplicate-name rejection with the existing id, and the requirement to preview and confirm before calling.

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

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

Every sentence carries a distinct instruction (source preference, batch semantics, transaction behavior, duplicate handling, confirmation step) with no filler. The opening fragment 'Culturas da empresa' is a slightly abrupt hook rather than a clean lead, and the density makes it a bit blocky.

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

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

For a mutation tool with an output schema, the description covers the missing pieces: write semantics, transactionality, batch limits, default farm behavior, and error reporting ('a resposta diz qual item e por quê'). Nothing an agent needs to invoke it safely is absent.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning: it frames 'itens' as a batch with a 50-item cap and explains the id/desativar/id_cultura_base tri-mode semantics and the default-fazenda behavior in narrative form, going beyond restating the schema.

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

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

States a specific verb (cadastrar/GRAVA) and resource (culturas da empresa) and points to the authoritative source (consultar_base_upcampo). It is clear what is written, though it does not explicitly distinguish itself from close siblings like cadastrar_variedade or cadastrar_safra.

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: prefer importing from the upCampo base, send the whole dictated list in one call (max 50), include vs alter vs desativar driven by the id/desativar flags, and ask the user before overwriting on a duplicate-name rejection. Alternatives and conditions are spelled out, not 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?

The description adds substantial behavior beyond the annotations: all-or-nothing transaction (if one item is rejected, none are saved), explicit rejection reasons (duplicate plate, duplicate name with existing id), default medidor behavior per equipment type, and the requirement to confirm with the user before writing to upCampo. These details are not derivable from the annotations alone. No contradiction with readOnlyHint=false, idempotentHint=false, or destructiveHint=false.

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

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

The description is information-dense and front-loads the core distinction between machines and implements. It uses three short paragraphs for rules, list semantics, and required confirmation. There is minor repetition (duplicate-name rule appears twice), but every sentence carries operational value.

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

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

For a batch registration tool with multiple fields, a transaction constraint, and an output schema, the description covers the critical behaviors an agent needs: default field values, conflict handling, all-or-nothing semantics, and the required user confirmation step. The output schema exists, so return-value explanation is appropriately omitted.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes further by explaining batch semantics for the 'itens' array (up to 50 per call, send all at once) and the combined effect of id and desativar, which enriches the parameter meaning beyond the individual schema 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?

The description names the resource precisely (máquinas, veículos, implementos) and distinguishes it from siblings by contrasting machines (with horímetro, abastecimento) and implements (with no meter, outside fueling). It also clarifies registration semantics like plate uniqueness per farm, making it easy to tell apart from cadastrar_tipo_equipamento.

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 operational context: send the whole list at once, use id to alter, id+desativar to deactivate, and 'mostre ao usuário a lista... e confirme antes de chamar.' It also handles the duplicate-name conflict by telling the agent to ask whether to alter. However, it does not explicitly name an alternative tool (e.g., consultar_cadastros to check existing records).

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 flag a non-read, non-destructive, non-idempotent write; the description goes far beyond them by disclosing the all-or-nothing transaction ('se um item for recusado, NENHUM é gravado'), duplicate-document and duplicate-name rejection behavior, the response reporting the offending item, and the required user confirmation 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?

Dense but efficient: each sentence carries either a rule (masking, duplicates, all-or-nothing) or an instruction (batch the whole dictation, confirm before writing). The vague opening line and the some-what repetitive duplicate-name warning cost it the top mark.

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

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

For a mutation tool with an output schema present, the description covers the essential behavioral contracts (transactionality, rejection reporting, confirmation flow) so return values needn't be described. Only minor gaps remain, such as what fields are required beyond `razao_social` on insert.

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 real meaning: the 50-item list cap, the batch semantics of `itens`, the `id`-driven insert/edit/deactivate branching, and the unmasked document format. This goes beyond restating the schema.

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

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

The description names a specific verb+resource (registering company suppliers) and details the CRUD behaviors of the tool, plus the document-normalization rules. The opening 'Fornecedores da empresa' is slightly vague, and it never names which sibling (e.g. consultar_cadastros) it complements, but the operation itself 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?

It clearly states the conditions that pick each mode: no `id` inserts, `id` alone edits only supplied fields, `id`+`desativar` deactivates, and it instructs to show the list and confirm before calling. It does not explicitly contrast with sibling registration tools, but the when-to-use conditions are strong.

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 flag it as a non-read-only, non-destructive, non-idempotent write. The description goes well beyond that: all-or-nothing transaction semantics with per-item rejection reporting, duplicate-name rejection returning the existing id, name as the identity key used by UPí, team assembly happening elsewhere, and an explicit confirmation workflow. This is rich 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?

Well front-loaded: purpose first, then batch/transaction rules, then persistence target and confirmation. The double emphasis on 'nome repetido' (once in the intro, once in the batch paragraph) is slightly redundant, but overall it is tight and every paragraph 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?

Covers purpose, batching limit, transaction semantics, error reporting, duplicate handling, persistence target (upCampo), and the required user confirmation. With an output schema present, return values need not be explained. Nothing an agent needs to invoke this 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 description coverage is 100%, so the schema already documents each field (id, nome, codigo, desativar, valor_hora, fazenda). The description reinforces the 'id excludes/includes/alters/desactivates' semantics and the fazenda default, adding moderate value but largely mirroring the schema. Baseline 3 is appropriate.

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

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

Names the specific resource (funcionários da fazenda) and the concrete roles it covers, plus the downstream flows it feeds (execução de OS, abastecimento). Clearly distinguished from the many cadastrar_* siblings by being the only one dealing with people.

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

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

Gives strong operational guidance: batch up to 50, send everything the user dictated at once, show the list and confirm before calling. Implies when to use 'id' vs no 'id'. However it does not explicitly name the sibling to use for lookup (consultar_cadastros is referenced only inside the schema description of 'id', not in the tool description).

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

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

Annotations only declare non-read-only, non-destructive, non-idempotent. The description goes well beyond: all-or-nothing semantics ('se um item for recusado, NENHUM é gravado'), the response naming the offending item and reason, duplicate-name rejection returning the existing id, that deactivation hides from lists but preserves history, and that writes land in upCampo. That is the behavioral detail the annotations 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?

Four dense sentences, front-loaded with the resource scope and then the batch/write semantics. Every sentence earns its place, though the stray blank line and the layering of batch rules, duplicate handling and confirmation flow make it slightly heavier than 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?

An output schema exists, so return-shape explanation is unnecessary, and the description still notes the response identifies the rejected item and reason. Given the batch, confirm-before-write and deactivation semantics, nothing an agent needs to invoke this 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 description coverage is 100%, so `id`, `codigo`, `desativar`, `descricao` and `fazenda` are already documented per-field. The description consolidates the id/no-id/desativar interaction model but adds little syntax beyond the schema; the duplicate-name rule it contributes is behavioral rather than parametric. Baseline 3 is appropriate.

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

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

States a specific verb and resource (cadastrar local de estoque) and names the concrete scope: depósito, galpão, barracão. It also rules out silo and posto de abastecimento, which are handled by the portal, so an agent can distinguish this from siblings like cadastrar_talhao or consultar_estoque without opening a 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 tells the agent to batch everything the user dictated in one call (up to 50), and states the three operating modes: no `id` inserts, `id` updates only the given fields, `id`+`desativar` deactivates. It adds a workflow instruction (show the list and confirm before calling) and an exclusion (silo/posto via portal), leaving little 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 only say non-read-only, non-idempotent, non-destructive; the description adds the real behavioral contract: batch of up to 50 items, upsert-by-id semantics (no id = insert, id = partial update, id + desativar = soft delete keeping history), all-or-nothing transactionality, duplicate rejection with the existing id, and the target system (upCampo). This is exactly the beyond-annotations disclosure the dimension asks for.

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

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

Front-loaded with purpose and the cardinality rule, then batch semantics, then the write/confirm instruction; every paragraph carries distinct operational information. It is on the long side for a single tool, but there is little filler and no 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?

An output schema exists, so return values need not be restated, and the description still covers the one response detail that matters operationally (which item failed and why, on an all-or-nothing write). For a batch mutation with complex conditional semantics, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds aggregate-level meaning the per-field descriptions do not carry: the list is a single transactional batch, items are dispatched all at once, and the id/desativar combination drives insert-vs-update-vs-deactivate. That interplay is documented in prose rather than only in 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?

States a specific verb and resource in context: it records what is planted per talhão per safra, and ties the record to downstream artifacts (ordem de serviço, colheita, produtividade). That framing distinguishes it from cadastrar_safra, cadastrar_talhao and cadastrar_cultura without needing to name 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?

Explicit routing rules: one variety per talhão/safra, multiple varieties must go through the portal, and changing safra/talhão/cultura requires deactivating and re-including. It also tells the agent to confirm with the user before calling, which is an actionable usage condition rather than a generic disclaimer.

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 (readOnly=false, destructive=false, idempotent=false), the description discloses transactional atomicity ('é tudo ou nada'), duplicate-name rejection with the existing id returned, the AVISO about a talhão shared by two pluviômetros, and that writes go to upCampo. This is exactly the extra behavioral context annotations can't convey.

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

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

Front-loaded with the resource and then the mode rules; each paragraph is information-dense. Slightly verbose with some restatement of id semantics already in the schema, but nothing is wasted enough to drop a tier.

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 an output schema present, return values need not be explained, and the description still covers the failure-response content ('a resposta diz qual item e por quê'). Combined with the write-target and confirmation guidance, an agent has everything needed to 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 coverage is 100%, so baseline is 3; the description nevertheless adds meaning by restating id semantics (insert vs. alter vs. deactivate) and reinforcing the all-or-nothing and duplicate behaviors tied to those params. It stops short of adding syntax/format detail beyond the schema.

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

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

Opens with a specific verb+resource ('cadastrar pluviômetro') and immediately clarifies scope: rain gauges and the plots (talhões) each one covers. The reader can distinguish it from sibling cadastrar_* tools without opening the schema.

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

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

Explicitly routes all three modes: no `id` inserts, `id` alters only given fields, `id`+`desativar` deactivates. It also states batching (up to 50), the all-or-nothing rule, duplicate-name handling, and the mandate to show the list and confirm before calling.

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 declare the write profile (readOnly=false, idempotent=false, destructive=false), and the description adds substantial context beyond that: batch size up to 50, all-or-nothing transaction semantics with the failing item reported, duplicate-name rejection returning the existing id, the target system (upCampo), and a required confirmation step before writing. This is unusually complete behavioral disclosure.

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

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

Multi-paragraph but front-loaded with the resource definition, then the batch/mutation rules, then the confirmation requirement. Every paragraph carries a distinct instruction (routing, batch semantics, write target, confirmation). Slightly long, but nothing reads as 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 write tool with an output schema present, return-value detail is unnecessary, and the description still notes that the response identifies which item failed and why. Combined with the annotation profile and full schema coverage, an agent has everything needed to call it correctly, including the pre-write confirmation step.

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 already 100%, so the schema baseline is 3. The description adds operational semantics the schema only implies: the id/no-id/desativar tri-state behavior and the fact that `codigo` is auto-generated if omitted. It does not add extra detail on the typed boolean flags (semente, combustivel) or ncm, so it stays just above baseline.

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 (cadastrar) and resource (produto), and immediately scopes the resource by naming the product categories (defensivo, adubo, semente, combustível, peça). This distinguishes it cleanly from siblings like cadastrar_classe_produto and cadastrar_variedade without needing their schemas.

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

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

Explicit routing: use consultar_base_upcampo (visão produtos) to suggest unidade/classe/grafia, but register whatever the client confirms. It also states when to omit `fazenda` (default to current farm, only supply if another is named) and the when-to-use rule for `id`/`desativar`. Alternatives and exclusions are spelled out.

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

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

Beyond the annotations it discloses the transactional contract ('É tudo ou nada'), that the response identifies the offending item and reason, that duplicate names are refused with the existing id, and that deactivation removes the record from lists while keeping history. These are real behavioral traits (atomicity, error shape, conflict handling, write target upCampo) not derivable from readOnlyHint=false / destructiveHint=false / idempotentHint=false.

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 highest-value facts (required fields, write target) and organized into short paragraphs by concern (scope, batch modes, conflict handling, confirmation). It is denser than strictly necessary and mixes operational guidance with usage rules, but every sentence carries 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?

With an output schema present, return values need not be re-explained; the description instead covers everything an agent must decide before calling (mode selection, batching, confirmation, conflict handling). Nothing material is missing for a 2-parameter write tool.

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

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

Schema coverage is 100% so the per-parameter descriptions already do the heavy lifting (baseline 3). The description adds cross-field semantics not obvious from the schema alone: the início/fim pair defining the current safra, the id-vs-no-id rule governing include/alter, and id+desativar combination. No syntax or format beyond what the schema states is added.

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 (gravar/cadastrar) and resource (safras), and usefully scopes them as company-wide ('valem para todas as fazendas dela'), which distinguishes them from farm-scoped siblings like cadastrar_talhao or cadastrar_plantio. It never names a sibling explicitly, so the differentiation is inferred from scope rather than stated, keeping it from a 5.

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

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

It gives explicit when-to-use rules for every mode: no id = include, id = alter only the informed fields, id + desativar = deactivate. It also specifies the batch workflow ('mande tudo o que o usuário ditou de uma vez'), the required confirmation step, and how to react to a duplicate-name rejection (ask whether to alter). Little 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?

Goes well beyond the annotations: all-or-nothing atomicity with the offending item reported, duplicate-name rejection returning the existing id, the rule that an OS-used subtype cannot be renamed, the AVISO when the first subtype restricts an activity type's list, and the destination store (upCampo). The soft-delete semantics ('sai das listas, o histórico fica') align with destructiveHint=false rather than contradicting it.

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?

Long but dense and front-loaded, leading with the domain concept before the operational rules and the confirm-before-calling instruction. Each paragraph carries a distinct rule, though the prose is heavier than strictly necessary for a two-parameter 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?

With an output schema present, 100% schema description coverage, and full annotations, the description fills the remaining gap — atomicity, duplication handling, rename restriction and write target — so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: the 50-item limit, the id-vs-no-id contract for update/insert/deactivate, and the all-or-nothing consequence on the itens array. It does not clarify tipos_atividade being the COMPLETE list beyond what the schema already says.

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

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

States a specific verb and resource (cadastrar_subtipo) and spends its opening defining the domain object (subdivision of activity type shown on the OS), including how it behaves when linked. An agent can distinguish this from cadastrar_tipo_atividade without reading 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 explains the three modes — no id inserts, id updates only given fields, id + desativar deactivates — and instructs batching all user-dictated items into one call, plus a confirmation workflow. It does not name an alternative sibling for the insert case, so it stops short of full when/when-not routing.

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

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

Goes well beyond the annotations: map submission replaces the previous map, area may be omitted when a map is supplied (map area wins), the write is all-or-nothing with per-item rejection reporting, duplicate names are refused with the existing id, and the tool writes to 'upCampo'. Deactivation keeping history is consistent with destructiveHint=false.

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 resource and key data, then layers list semantics and map-handling rules. The length is justified by the tool's complexity, though the map/format paragraph could be tightened slightly.

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 everything an agent needs for a batch mutation tool: input format conversions, area/map precedence, id-based create/update/deactivate branching, atomicity, duplicate-name handling, and a confirmation step. An output schema exists, so return-value explanation is correctly omitted.

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

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

Schema coverage is 100%, so the schema carries the baseline, but the description adds genuinely interpretive meaning: the area/map precedence rule and the longitude,latitude → [latitude, longitude] inversion for KML/GeoJSON input. That is more than restating schema text.

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 definition names the resource (talhões) with its constituent data (área, setor, mapa) and then pins down the exact operations: 'Sem `id` inclui; com `id` altera só os campos informados; com `id` e `desativar` desativa.' An agent can tell this is the plot-registration tool and not a query tool like consultar_cadastros from the text alone.

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

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

Gives strong operative guidance: send all dictated items in one list, handle KML/GeoJSON by emitting one item per polygon, and show the list to the user before calling. It does not name a sibling alternative or state when not to use it, so it stops short of a 5.

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

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

Annotations only give the generic write profile (readOnly=false, destructive=false, idempotent=false). The description adds high-value behavior beyond that: all-or-nothing atomicity ('se um item for recusado, NENHUM é gravado'), duplicate-name rejection with the existing id returned, the requirement to confirm with the user before writing, and that it writes to upCampo.

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 domain concept before the operational mechanics, and the write/confirm warning is placed last as a call-to-action. Slightly redundant in repeating the 'send everything in one call' instruction twice, 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?

For a 2-parameter batch-write tool with a full output schema, the description covers prerequisites, batch semantics, failure behavior, and confirmation flow. Return-value details are correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter mode semantics the schema does not spell out: no id = include, id = partial update, id+desativar = deactivate, plus the 50-item batch limit and the model-derived default name. This is genuinely additive but overlaps the per-field schema text.

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 (register activity types) and defines what an activity type is with concrete examples (plantio, colheita, aplicação, adubação). It distinguishes itself from the many cadastrar_* siblings by explaining the model-driven creation flow that only this tool has.

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 context: activity types are required before a service order can be launched, and each must be derived from a model fetched via consultar_base_upcampo (visão tipos_atividade). It also spells out the include vs. alter vs. deactivate conditions and instructs sending everything in one call.

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

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

Annotations only tell us this is a non-read-only, non-idempotent write; the description adds substantial context beyond that: the all-or-nothing transaction (one rejected item blocks the whole batch), the duplicate-name rejection that returns the existing id, the deactivation semantics (leaves lists, history retained), the 50-item cap, and the code-generation rule tied to abreviação. This is exactly the behavioral disclosure annotations 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 what the tool is, then modes, then transaction/duplicate behavior, then the confirm-before-write instruction. Multi-paragraph but each block carries distinct information; no filler sentences.

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

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

An output schema exists, so return values need no explanation. The description still covers selection modes, prerequisites (helpers for ids/names), failure semantics, confirmation flow, and the default-vs-explicit fazenda choice — nothing an agent needs to call 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 already 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: it explains how abreviacao drives the generated equipment code (abreviação + número, e.g. TR0001), reiterates the batch semantics of itens, and justifies the fazenda default behavior. Not fully additive on every field, so a 4.

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

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

States a specific verb (grava/cadastra) and resource (tipo de equipamento, e.g. Trator, Colhedora), and explicitly distinguishes itself from siblings by naming consultar_base_upcampo for suggested names and consultar_cadastros for ids. An agent can identify this as the write tool for equipment-type master data without opening any schema.

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

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

Gives clear mode-selection rules (no id = insert, id = update only informed fields, id + desativar = deactivate) and names the helper tools for related lookups. It also mandates confirmation before calling. It stops short of explicitly contrasting against the sibling cadastrar_equipamento, so it is a strong 4 rather than a 5.

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

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

Annotations only declare the safety profile (not read-only, not idempotent, non-destructive). The description adds hard behavioral facts the annotations cannot: all-or-nothing atomicity with no partial writes, the response identifying which item failed and why, duplicate-name rejection including the existing id, deactivation preserving history, and an explicit instruction to confirm with the user before calling.

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

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

Front-loaded with the resource definition, then batching rules, then mode semantics, then the atomicity warning, ending with the write/confirm directive. Four short paragraphs, each earning its place. Slightly dense 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?

An output schema exists, so return-value detail is unnecessary, and the description still covers the failure-reporting shape. For a 2-parameter batch-write tool with rich annotations and a nested-item schema, an agent has everything needed: modes, limits, atomicity, duplicate handling, and confirmation policy.

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

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

With 100% schema coverage, the baseline is 3, but the description adds real semantics: the id/no-id/desativar tri-state is spelled out narratively, and it clarifies the 50-item cap and list-batching intent. It reinforces rather than merely repeats the schema, though it does not add new meaning for codigo, ciclo_dias, or tecnologia.

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

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

The description names a specific resource (variedades/cultivares) and the operation (registration into upCampo), with the constraint that each belongs to an already-registered cultura. It is clearly distinguishable from cadastrar_cultura and cadastrar_produto via the explicit 'cada uma de uma cultura já cadastrada' framing. The opening sentence reads more as a definition than a verb+action, but the intent 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?

It gives concrete operating instructions: send the whole user-dictated list at once, up to 50 per call, and a clear mode table (no id = include; id = update; id + desativar = deactivate). It also tells the agent to ask the user on a duplicate-name conflict. It stops short of naming alternative tools for adjacent tasks (e.g., consultar_cadastros for listing).

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 openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: which records are importable by ID versus advisory-only, the explicit warning not to copy product data ('Não copie: cadastre com o que o cliente confirmar'), and the scale constraint on produtos. Minor gap: no mention of result limits/pagination beyond the schema's limite.

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 one-sentence purpose and then uses a scannable bulleted list keyed to the enum values, so every bullet maps to a branch the agent must choose between. It is somewhat long, but the length is earned by six views that need differentiation.

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 unnecessary. The description covers all six view branches, the suggestion-vs-import distinction, and ID hand-off; combined with the rich schema descriptions (including the fazenda default), an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by expanding each 'visao' enum value into an explanation of its content and downstream use, which the schema only labels. It also reinforces how the returned codes (ID_CULTURA_BASE, ID_MODELO, CODIGO) should be consumed.

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 (query the upCampo reference/help base) and then decomposes the six 'visao' values, explaining exactly what each returns (phenological stages, activity-type models with NATUREZA, product classes, products, equipment types, units). It explicitly links each result to the sibling registration tool it feeds (ID_CULTURA_BASE -> cadastrar_cultura, ID_MODELO -> cadastrar_tipo_atividade), so an agent can distinguish it from the cadastrar_* and consultar_* siblings without opening any schema.

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

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

Gives per-view usage context: 'produtos' requires a search because there are 1000+, models are chosen by nature and name, and results are described as either carried into the farm (culturas, tipos_atividade) or merely suggestive (classes, produtos, tipos_equipamento, unidades). It does not explicitly say when to prefer this over lookalikes such as consultar_cadastros or buscar_ajuda, so routing to alternatives 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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses filter-matching behavior (substring match, case- and accent-insensitive, except '(valor exato)' fields like código/placa/número), that the response carries total_disponivel, that fazenda defaults to the user's current farm and one farm is queried per call, and explicit pagination advice ('Chame uma vez só… nunca repita a consulta mudando só o limite'). This is rich behavioral context that annotations alone 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?

It is long, but the length is largely earned by 16 distinct views; it is front-loaded with the resource inventory and the starting-view guidance, then bulleted per view. Some redundancy exists because the per-view 'Filtros:' lists duplicate what the schema already states for each parameter.

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 an output schema present, return values need not be re-explained, yet the description still flags total_disponivel and limit behavior. For a 0-required, 18-param, 16-view tool it covers view selection, filtering, defaults, and pagination thoroughly — an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter's applicable views; baseline would be 3. The description adds meaning by restating which filters apply per view and, more importantly, by explaining the text-filter matching semantics and the exato-marker exception that the schema does not encode.

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

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

The description states a specific verb+resource and enumerates exactly which registries are covered (safras, culturas, variedades, talhões, plantio, produtos, fornecedores, etc.), plus its relationship to the cadastrar_* tools that consume the returned ids. An agent can immediately tell this is the read/registry-query tool and what data it exposes, rather than a create or operational tool.

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

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

It gives strong internal routing guidance: default visao=andamento, that andamento is where an implementation starts, the recommended ordering of the rollout, and per-view filters. It does not explicitly state when NOT to use it or contrast against the sibling consultar_* tools (estoque, produção, frota), so it stops short of full when/when-not coverage.

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 readOnlyHint and openWorldHint, so the description carries most of the behavioral load and does so well: it discloses substring/case/accent-insensitive matching except for '(valor exato)' fields, that responses include total_disponivel, and the pular+limite pagination pattern. This is context an agent needs and that neither annotations nor schema provide.

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

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

The overview and defaults are front-loaded, then a clean per-visao breakdown. It is longer than strictly necessary, with some repetition of filter lists that also appear in the schema, but every section is scannable 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 10-parameter tool with five distinct visões, the description covers each mode, its filters, the default, pagination, and filter-matching semantics. An output schema exists, so return-value explanation is not required, and nothing needed 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 already 100%, so the schema documents formats and per-visao applicability. The description still adds value by consolidating which filters apply to which visao and clarifying date formats and the 'fazenda' default behavior. Since the schema already repeats much of this, a 4 rather than 5.

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 sentence gives a specific verb-and-resource statement: rain registered by pluviometer, per collection, per plot, or consolidated in the harvest, plus the pluviometer registry. It also implicitly distinguishes itself from the write sibling lancar_chuva by framing the tool as a query. An agent can tell exactly what this returns without opening the schema.

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

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

The description enumerates all five 'visao' values with their applicable filters and explicitly routes the agent: use 'pluviometros' to count, use 'pluviometros_talhoes' for the coverage mapping, and the default when 'visao' is omitted. It also adds a strong operational rule ('call once with the limit you will use; never repeat changing only the limit') and points to lancar_chuva for the ID to use.

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 declare readOnlyHint=true and openWorldHint=false, and the description reinforces the read-only nature while adding rich behavior: never compare dates, use pre-computed SITUACAO_ENTREGA/DIAS_ATRASO, never subtract quantity columns, exclude 'Saída de estoque' items from purchase questions, call once with the final limit, and response totals via total_disponivel. This is well beyond what annotations supply.

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?

Structurally strong: a front-loaded purpose sentence, a chains section, business-rule paragraphs, then a per-visão bullet list. It is long, but the length is justified by 33 parameters and 6 views. Minor redundancy exists (restating defaults and filter behavior in multiple places), keeping it off a full 5.

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 33 parameters, 6 views, and an output schema that already covers return values, the description covers everything needed: default visão (pedidos), filter semantics per view, agrupamento behavior, pagination guidance (pular/limite/total_disponivel), and the domain rules an agent would otherwise get wrong.

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

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

Schema coverage is 100%, so the schema baseline already documents each parameter. The description nevertheless adds meaning beyond the schema by mapping each visão to its filters/group-by dimensions, defining the cadeia relationships between requisicao/cotacao/coleta/pedido, and clarifying exact-value vs partial-match filters. It stops short of some per-parameter detail the schema already carries, so a 4 rather than 5.

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

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

Opens with a specific verb+resource ('Requisições, cotações, coletas de preço e pedidos de compra') and immediately states the negative scope ('Somente consulta: não aprova, não cria nem altera pedido'). This distinguishes it from sibling read tools and from any approval action, so an agent can route without opening the schema.

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

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

The description explicitly says when to use each visão, when to use agrupar_por instead of listing, when trilha requires a prior document lookup, and how to select or exclude item types. It also gives concrete routing rules ('Pedidos atrasados' → situacao_entrega ['Atrasado']) and exclusion rules, leaving little 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=true and openWorldHint=false, and the description goes well beyond them: substring/case/accent-insensitive text matching, the '(valor exato)' exception for codes and plates, the presence of 'total_disponivel' in the response, and anti-pattern guidance against repeating queries with different 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?

Front-loaded with the purpose, then cleanly bulleted by view; the closing paragraph on filtering, total_disponivel and single-call discipline is dense but earned. Some per-view filter lists duplicate what the schema already states, which costs a little 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?

For a 13-parameter read-only query tool with an output schema, the definition covers everything an agent needs: view selection, filter applicability, text-matching semantics, pagination, and result-size signaling. Nothing material is missing.

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

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

Schema coverage is 100% and each parameter already documents which views it applies to, so the description largely restates that. It still adds real meaning the schema lacks: the substring matching rule and the exact-value caveat for codigo_os, plus the default-farm behavior for 'fazenda'.

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 (custo dos insumos aplicados) and its two aggregation axes, then enumerates the three concrete views (total_talhao, por_classe, por_ordem). An agent can distinguish this from consultar_producao, consultar_financeiro and consultar_ordens_servico without opening a 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 names the default view when 'visao' is omitted, lists which filters apply to each view, and gives direct invocation guidance ('Chame uma vez só, já com o limite que a resposta vai usar — nunca repita a consulta mudando só o limite'). It also tells the agent when to supply 'fazenda' versus omitting it for the current farm.

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 cover read-only/openWorld, so the description adds substantial behavioral context: pagination via total_disponivel, one-call discipline, accent/case-insensitive partial matching with '(valor exato)' exceptions, and unit-dependent non-summing of quantities. It is docked for an internal inconsistency — it repeatedly claims listings are capped at 30 rows while the schema allows limite up to 500 — which could mislead an agent about result size.

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 purpose is front-loaded, but the text is roughly 700 words and repeats the agrupar_por guidance three times (opening, mid-body, closing paragraph), with the last two paragraphs largely restating earlier rules. Dense and useful, yet it could lose a third of its length without information loss.

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 15-parameter, four-visão analytical tool, the description covers filters per visão, aggregation output fields, edge cases (negative balance, loteless products, products without class) and defaults. Return-field semantics are explained even though an output schema exists, leaving no obvious 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 coverage is already 100%, but the description materially exceeds it: it explains which dimensions each visão accepts, why 'Defensivo'/'Adubo' are not valid classe_produto values, that 'Sem classe no cadastro' must be shown and never reassigned, and that SALDO_NEGATIVO must be reported separately. This is analytical meaning the schema cannot express.

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

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

Opens with a specific verb+resource scope (saldo por local, lotes com validade, movimentação) and immediately routes the sibling case ('documento que originou a entrada... use a consulta de pós-colheita'). An agent can separate this from consultar_pos_colheita and the other consultar_* tools without opening the schema.

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

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

Explicitly states when to aggregate vs list ('para totais e contagens use agrupar_por... nunca liste para contar ou somar'), how to resolve group questions ('defensivos', 'adubos') that the class filter cannot answer, and directs to the locais visão when a group-specific location is needed. Alternatives and anti-patterns are named, not inferred.

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 openWorldHint=false, and the description adds substantial behavioral context beyond them: default 30-day window for extrato, pagination via total_disponivel, limit versus grouping behavior, estorno handling, and currency aggregation rules. No annotation contradiction.

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

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

Organized into clear sections and view-specific bullets, with purpose and scope front-loaded. However, it is very long and repeats view-applicability details that the schema also documents, so it is not maximally concise despite the tool's complexity.

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

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

For a 36-parameter, multi-view tool with an output schema, the description covers defaults, return-shape hints, grouping behavior, pagination, and edge cases. The output schema reduces the need to restate return values, but the added operational context makes the definition 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?

Even with 100% schema coverage, the description adds meaning beyond the schema: text filters match by trecho except exact-value parameters, situacao must be used instead of date comparison, moeda grouping rules, and interpretation of VALOR_* fields. This materially supplements how parameters should be used.

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 set (contas a pagar/receber, saldo e extrato bancário) and scope (somente consulta: não dá baixa nem lança título), which distinguishes it from lancar_* siblings. Although it does not name every consultar_* sibling, the domain and read-only nature are 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?

Provides explicit guidance for each visão, states the default visão, and explains when to use agrupar_por versus listing. It also clarifies when resumo_conta is inappropriate because it does not accept period, directing the user to parcelas instead, covering alternatives well.

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 carry readOnlyHint/openWorldHint, yet the description adds substantial non-obvious behavior: the default view, substring/accent-insensitive matching vs '(valor exato)' filters, the 'total_disponivel' response field, one-call pagination advice, and the critical data-quality warning that DATA_FINALIZACAO is only trustworthy when status is Finalizado.

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 summary followed by a scannable per-view bullet list, then global filter semantics and the calling rule. Length is justified by the 23-parameter surface, with only minor overlap between the bullet lists and the schema's own view annotations.

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

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

For a six-mode, 23-parameter query tool with an output schema, the description covers mode selection, defaults, filter semantics, response metadata, and pagination expectations. Nothing essential for a correct first call is missing, and the maintenance-order date caveat prevents a plausible misuse.

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 3-baseline applies, but the description adds cross-cutting meaning the schema lacks: global matching semantics ('casa por trecho, sem diferenciar maiúsculas nem acento') and the exception marking for exact-value filters. It also consolidates which filters belong to each view, though much of that duplicates the schema's per-parameter 'Vale nas visões' notes.

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

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

Opens with a specific verb+resource and enumerates the covered subdomains (cadastro, abastecimento, ordens de manutenção, planos, custos), then explicitly separates itself from the sibling consultar_ordens_servico ('Ordem de manutenção é coisa distinta de ordem de serviço agrícola'). An agent can route without opening the schema.

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

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

Documents the 'visao' routing with per-view filters, states the default when visao is omitted, and gives calling guidance ('Chame uma vez só, já com o limite que a resposta vai usar — nunca repita a consulta mudando só o limite'). It flags the maintenance-vs-service-order distinction but does not name when to prefer consultar_ordens_servico or consultar_custos by tool name.

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

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

Annotations already cover read-only/no-open-world, but the description adds real behavioral context beyond them: default visao, case- and accent-insensitive partial text matching versus exact-value filters, the presence of total_disponivel in the response, and pagination strategy via pular/limite. This is unusually rich disclosure for a query 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 with purpose and exclusion, then an efficient bulleted breakdown per view, then filtering/limit rules. Length is justified by 13 parameters and 5 views, though a few lines restate schema-documented view applicability.

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 13-parameter, multi-view query tool with an output schema present, the description covers defaults, filter behavior, pagination, and response metadata (total_disponivel) so an agent can invoke it correctly in one shot with the right limit.

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 already 100% and documents per-view applicability of each filter, so the description mostly parallels it; however it adds genuine value by explaining the default visao and the text-matching semantics (partial vs exact) that the schema does not state.

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

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

States a specific verb+resource (field survey of pests found, monitored points, phenology) and explicitly distinguishes itself from the sibling domain of pesticide application (consultar_ordens_servico). An agent can tell what this tool returns and what it is not without opening the schema.

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

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

Gives explicit when-to-use guidance per view (levantamentos, ocorrencias, pontos, fenologia, registros) with the applicable filters for each, states the default view (ocorrencias), points to listar_safras for valid safra values, and routes the agent away from pesticide application. Also instructs calling once with the intended limit rather than re-querying.

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 cover the safety profile (readOnlyHint, openWorldHint). The description goes well beyond: it discloses text-matching semantics (substring, case- and accent-insensitive, except exact-value filters), the meaning of 'total_disponivel', default visao, and pagination strategy. None of this is derivable from the annotations or schema alone.

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

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

Front-loads the scope and the frota exclusion, then uses a tight bulleted block for the visões. Some filter lists duplicate the schema's per-visao 'Vale nas visões' notes, which is redundant, but the structure keeps it scannable and nothing is padded 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?

With 18 optional params, full schema coverage, an output schema, and read-only annotations, the description supplies everything missing: visao selection, default behavior, filter semantics, total_disponivel, and the single-call/limit rule. An agent could call this correctly without further context.

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

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

Schema coverage is 100% and the schema already states per-visao parameter validity, so the baseline is 3. The description earns a notch more by adding matching semantics that change how parameters behave ('aplicacao' matches 'Aplicação'; exact-match params like codigo require the full value), which tells the agent how to format filter values.

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

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

Opens with a specific resource and scope ('Ordens de serviço da lavoura: plantio, aplicação, adubação, colheita') and immediately carves out what does NOT belong ('Combustível e manutenção de máquina não entram aqui — são frota'). This distinguishes it from the sibling consultar_frota without the agent needing to open 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 enumerates the four 'visao' modes with the rows and filters each returns, states the default when 'visao' is omitted, and names the negative case (frota tools). It also gives anti-pattern guidance ('Chame uma vez só... nunca repita a consulta mudando só o limite'), which is exactly the kind of behavioral routing an agent needs.

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 readOnlyHint/openWorldHint; the description adds real behavioral context — 30-row listing caps, total_disponivel, partial (accent/case-insensitive) text matching vs exact-value filters, server-side summing with MAIOR_*/MENOR_* aggregates, and pagination via pular/limite. One caveat: it repeatedly asserts 'máximo 30 linhas por chamada' while the schema's limite allows up to 500, which is an internal tension an agent must reconcile.

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 front-loaded well and dense with useful rules, but several statements are repeated nearly verbatim — the 30-row listing cap appears in four view bullets, and the 'use agrupar_por instead of summing' instruction is stated twice. The length is justified by complexity, yet the redundancy costs it a point.

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, six-mode tool with an output schema, the description covers intent routing, filters per view, aggregation semantics, unit conventions, defaults, and result-shape fields (QTDE_LINHAS, MAIOR_*, total_disponivel), so an agent can call it 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 already 100%, but the description goes further: it documents per-view applicability of each filter and the exact set of agrupar_por dimensions each view accepts, plus the derived-metric formulas (SACAS_LIQUIDAS = PESO_LIQUIDO_FINAL/60, ARROBAS_FAZENDA = PESO_FAZENDA/15) and the advice to group by setor+talhao together.

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 enumerates exactly what the tool covers — romaneios de colheita/saída, fardos de algodão, coletas e contratos — and frames it as the originating documents of stock movement, which cleanly separates it from siblings like consultar_estoque and consultar_producao. The six views are named explicitly, so an agent can match an intent to the tool without opening the schema.

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

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

Explicit routing rules are given: use agrupar_por for any total, never list to sum, that the listing is capped and meant for inspecting specific documents, that productivity comes from consultar_producao, and that safra names come from listar_safras. It also states the default view when visao is omitted and that queries are single-farm, with instructions to omit fazenda unless the user names another.

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 openWorldHint=false, so safety is covered. The description adds substantial domain behavior: unit semantics (sc/ha for grains, @/ha otherwise), the rule that empty TIPO_COLHEITA counts as grains, empty QTDE_REGISTROS_* in grains, and substring/case/accent-insensitive text matching. It does not discuss pagination edge cases beyond pular, keeping it at a 4.

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 most decision-relevant semantic (productivity units) before the view table, and every block earns its place. It is dense and longer than average, but the structure (unit rules, view list, filter behavior, pagination) is scannable rather than padded.

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 an output schema present, return values need no explanation; the description covers the remaining gaps an agent needs – view semantics, filter matching, unit interpretation, total_disponivel, and pagination via pular/limite. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: the exact-value vs. substring filter distinction, the default visao, and the productivity-unit interpretation tied to filters. It largely restates the per-view applicability already present in the schema, so it stops short of 5.

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 and scope: production data (area, harvest, productivity) broken down by safra, cultura, setor, talhão or variedade, and explicitly routes romaneio counts to the sibling consultar_pos_colheita. An agent can distinguish it from the many other consultar_* tools without opening a 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?

Explicit guidance: default visao is talhao when omitted; call once with the final limit rather than re-querying; and romaneio quantities live in consultar_pos_colheita instead. Covers when-to-use, when-not, and named alternatives.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the write/non-idempotent profile is known. The description adds genuine value beyond that: it names the write target ('GRAVA no upCampo') and mandates a confirm-before-call and report-after-write protocol. It does not mention permission/auth requirements, keeping 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?

Front-loaded with the core verb and resource, then moves efficiently into prerequisite tool, conditional branches, and the confirmation protocol. The lines are short and purposeful, though the interno/externo field lists partially duplicate the schema.

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

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

With an output schema present, return values need not be described, and the 100% schema coverage handles parameter detail. The description covers the main create workflow and confirmation loop well; the alter-existing path via id_lancamento is documented only in the schema, a minor 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 100%, so the schema already documents all 16 parameters including the Interno/Externo conditionals on id_bomba, id_produto, descricao_posto, and preco_litro. The description restates those same conditional requirements, adding emphasis but little new semantic detail, 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 ('Registra um abastecimento de equipamento'), which clearly places it among the lancar_* write tools and disambiguates it from the consultar_* readers. An agent can tell immediately that this creates a fueling record rather than querying one.

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

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

Gives explicit branching guidance: use consultar_frota first to find the equipment, then choose Interno (id_bomba) or Externo (descricao_posto, id_produto, preco_litro) with the required fields for each. It also prescribes the interaction workflow (summarize and confirm before calling, report after writing), leaving little 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 only give the generic readOnly=false/destructive=false/idempotent=false profile. The description adds the critical non-obvious trait that the upCampo procedure forces today's date and rejects any other (including via WhatsApp), plus a mandatory summarize-and-confirm workflow before writing. These are exactly the behaviors annotations cannot express.

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

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

Long but front-loaded: purpose first, then discovery order, then the date constraint, then the exclusive-field rules. Nearly every sentence is actionable operational guidance, though the mm/condicao_tempo rules slightly duplicate the schema wording.

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

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

For a write tool with a rich output schema (so return values need no explanation), the description covers everything an agent needs: discovery prerequisite, date limitation, field exclusivity, ambiguity handling, duplicate check, and confirmation workflow. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents fazenda, milimetros, id_lancamento, condicao_tempo and id_pluviometro. The description restates the mm-vs-condicao_tempo exclusivity that the schema already encodes, adding little parameter-level meaning beyond the baseline.

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

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

Opens with a specific verb+resource: "Registra a leitura de um pluviômetro". It immediately differentiates from the read-only sibling by routing discovery to consultar_chuva, so an agent can tell the write tool apart from the query tool without opening schemas.

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

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

Extremely explicit: tells the agent to look up the pluviômetro ID via consultar_chuva first, which view to use for talhão lookups, the today-only date rule, the portal fallback for past dates, the mm-vs-condicao_tempo exclusive cases, the two-pluviometer-per-talhão ambiguity, and the pre-flight duplicate check. When/why/when-not are all covered.

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 only the generic safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds behavior an agent cannot infer: all-or-nothing atomicity ("se faltar em um item, a nota inteira é recusada e nada é gravado"), the side effect that upCampo auto-registers a missing fornecedor, and the confirm-before-write workflow. These are exactly the traits annotations cannot express.

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

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

Front-loads the core purpose, then layers mode requirements, the critical id_local_estoque constraint, and the write/confirm workflow – a logical order with no wasted sentences. Slightly dense, and a few clauses (fornecedor sourcing, produto_descricao) echo schema text, but nothing is 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 13-parameter, nested-item write tool this is thorough: it covers both operating modes, required-field logic, dependency tools, the atomicity failure mode, the auto-cadastro side effect, and the confirmation workflow. An output schema exists, so return values need not be explained, and no gap remains that would cause a failed call.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds cross-parameter meaning beyond the schema – how tipo drives which of numero/descricao/fornecedor become required, that produto_descricao substitutes for id_produto when the product is unregistered, and that a single missing id_local_estoque rejects the whole note. That is genuine semantic value on top of an already complete 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 and resource ("Registra uma entrada de material no estoque") and immediately splits the operation into its two distinct modes ("Entrada avulsa" vs "Entrada com nota fiscal"), so an agent knows exactly what this tool produces. The resource is unambiguous against all lancar_* siblings (abastecimento, chuva, OS), which cover entirely different domains.

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 mode-specific conditions (avulsa needs descrição, nota fiscal needs número and fornecedor) and routes the agent to dependency tools: fornecedor from consultar_estoque or an existing cadastro, id_safra from listar_safras, id_local_estoque from consultar_estoque visão "locais". It also instructs to summarize and confirm before calling. It stops short of explicitly naming an alternative entry tool to prefer under some condition, but the branching guidance is strong.

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 a non-read-only, non-idempotent write with no destructive hint. The description adds value beyond them: it names the persistence target ('GRAVA no upCampo'), states a validation constraint on a required field, and mandates summarizing and confirming with the user before calling plus reporting the result afterward.

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 short sentences that are front-loaded: purpose first, then the lookup prerequisite, then the constraint, then the write/confirm protocol. No filler, though the 'GRAVA no upCampo' line and the post-write reporting instruction sit somewhat disjointedly after the data constraint.

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 write tool with annotations and an output schema, the description covers the operational essentials (what is captured, the lookup prerequisite, the date constraint, the confirmation protocol). It does not surface that supplying id_lancamento switches the call to an update of an existing lançamento, which is the main residual 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 100% across 20 parameters, so the schema already documents each field, including the tricky id_lancamento update mode and the grouped-talhão variants. The description only gestures at the main fields (área, horas, equipamento, operador) and adds no syntax or format detail 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 (Registra) and resource (execução de uma ordem de serviço agrícola), then enumerates the core data captured (área, horas, equipamento, operador). The framing as 'execução' rather than the order itself cleanly separates it from the sibling lancar_ordem_servico, and it names consultar_ordens_servico as the lookup path.

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

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

Explicitly routes the agent to consultar_ordens_servico to obtain the ordem and its talhões, and states a hard precondition ('A data não pode ser futura'). It also prescribes a confirm-before-write workflow. What is missing is an explicit when-not-to-use note (e.g. the alter-vs-create distinction).

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

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

Annotations already declare this is a write, non-idempotent, non-destructive operation. The description adds real behavioral context beyond that: it GRAVA no upCampo, requires summarizing the payload and confirming with the user before calling, and reporting back afterwards. Minor gap: the schema supports altering/removing existing items via id_lancamento/remover, yet the text says the tool 'só cria a ordem', so the update path is under-disclosed.

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

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

Front-loaded with the core purpose, then prerequisites, then the exclusion, then the create-vs-execute distinction, then the write/confirm/report workflow. Every sentence carries 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 return values need not be described, and the write workflow (confirm before, report after) is covered. The remaining shortfall is the unmentioned alter-mode (id_lancamento plus remover flags on nested items), which an agent must discover from the schema alone.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already carries parameter detail. The description adds sourcing semantics not in the schema by tying safra, talhões, produtos and equipamentos to their originating query tools, and clarifies the boundary that combustion/maintenance items are out of scope.

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

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

States a specific verb+resource ('Cria uma ordem de serviço agrícola') and enumerates the covered activity types (plantio, aplicação, adubação, colheita). It explicitly differentiates from the sibling lancar_execucao_os and from fleet logging, so an agent can distinguish it without reading another 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?

Gives explicit prerequisites (resolve safra/produção/estoque/frota first, naming listar_safras, consultar_producao, consultar_estoque, consultar_frota), an explicit exclusion (fuel and machine maintenance belong to frota, not agricultural orders), and an explicit alternative for execution (lancar_execucao_os). Both when-to-use and when-not-to-use are covered.

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 openWorldHint=false, so safety is covered. The description adds behavioral context: it returns the full article with structured formatting and includes a 'related' list for navigation. However, it doesn't mention pagination or size limits, but the structured nature suggests completeness for an article.

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 concise sentences that are front-loaded with the core purpose and then the usage condition and related-article feature. Every clause adds value without redundancy.

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

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

For a read-only tool with a simple, fully-documented single parameter and an output schema, the description covers what it returns, when to use it, and how to navigate related articles. It is complete for the agent's needs.

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

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

Schema coverage is 100%, so the parameter 'artigo' is fully documented in the schema (accepts slug or article URL). The description doesn't add parameter details beyond the schema, so baseline would be 3. However, it reinforces the expected input by referencing 'como veio de buscar_ajuda' in the schema description, and the overall context implies singular article retrieval. Score 4 reflects the schema's completeness and the description's implicit support.

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 ('Devolve um artigo inteiro da Central de Ajuda') and describes the return content in detail (menu location, fields, steps, FAQ). It clearly distinguishes itself from the sibling buscar_ajuda by providing the full article rather than a snippet.

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 when to use: 'Use depois de buscar_ajuda, quando o trecho não bastar para responder.' It names the alternative tool and the condition that selects it, and further explains how to follow related articles without a new search.

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 openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it reports the authenticated user, the company, released subjects per farm, and the current farm, which helps the agent interpret the result. It omits any auth preconditions or rate-limit notes, keeping it just below 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, front-loaded with what the tool returns before the usage guidance. The final sentence about not being needed before a common query is valuable but slightly leaning, keeping it just under maximally tight. No filler 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?

An output schema exists so return values need not be spelled out, yet the description still summarizes the returned content (user, farms, company, subjects, current farm), and the usage guidance is complete. Nothing an agent needs in order to call this correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a no-argument, context-resolving 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 specific verbs and resources: it reports the authenticated upCampo user and lists the farms (branches) available, along with company, released subjects, and the current farm. This is clearly distinguishable from sibling list tools like listar_safras and the cadastrar/consultar family.

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 gives when to use (user asks which farms exist, or cites a farm name to verify) and when not to (not required before a common query, since tools default to the current farm). This directly routes the agent and prevents a needless call.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the result set deliberately includes empty seasons (QTDE_TALHOES 0, sem cultura) and marks which safra is current — edge cases an agent would otherwise guess wrong about. It does not mention pagination or ordering, keeping 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?

Three tight sentences: what it returns first, the inclusion edge case second, usage and the ID_SAFRA consumer last. No filler, and the most decision-relevant content 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?

An output schema exists, so return values need no prose, yet the description still flags the non-obvious ones. Combined with the 100%-covered lone parameter and the safety annotations, an agent has everything needed to call this correctly.

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

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

There is a single parameter and schema coverage is 100%; the schema itself documents the default-fazenda behavior and the one-fazenda-per-query rule. The description adds nothing about the fazenda argument, 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?

States a specific verb (lista) and resource (safras da fazenda) and enumerates what comes back — período, culturas, área total, indicação de safra corrente. The explicit inclusion of safras with QTDE_TALHOES 0 (sem cultura) distinguishes it from any tool that would only return planted seasons, and cadastrar_safra is clearly the write counterpart.

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 antes de filtrar qualquer consulta por safra" states the prerequisite condition explicitly, and "ID_SAFRA é o que cadastrar_plantio pede" routes the agent to the sibling that consumes the output. This is a when-to-use rule plus an alternative/downstream pointer, not inference.

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