sei_criar_documento

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

Annotations (readOnlyHint=false, destructiveHint=false) indicate a non-read-only, non-destructive operation. The description adds that the document is created empty, which is useful for setting expectations, but does not detail other behavioral aspects like permissions required or side effects (e.g., whether the process is modified). The description does not contradict annotations.

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

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

The description is a concise paragraph with a bullet list for parameters, placed after the main action statement. It front-loads the purpose. The parameter list could be integrated more tightly, but overall it is efficient with no redundant 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?

Given the tool's complexity (5 parameters, optional output schema), the description covers key usage: creation of empty internal documents and hints at post-creation workflow. It does not explain the return value, but since an output schema exists (context signal), that omission is acceptable. It could mention that the tool returns the document ID for further operations.

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

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

The input schema has 0% description coverage, but the description fully explains all 5 parameters: it specifies the format for processo, recommends sei_pesquisar_tipos_documento for id_serie, defines descricao as title, provides numeric values for nivel_acesso (0=público, 1=restrito, 2=sigiloso), and marks id_unidade as optional. This adds substantial meaning 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?

Description clearly states 'Cria um novo documento interno (nativo) em um processo SEI.', identifying the specific verb (cria), resource (documento interno), and context (processo SEI). This distinguishes it from sibling tools like sei_criar_documento_externo, which creates external documents.

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

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

The description provides context: it creates an empty document and directs the user to other tools for content insertion (sei_listar_secoes, sei_editar_secao) and to fetch type codes (sei_pesquisar_tipos_documento). However, it does not explicitly state when to use this tool vs. its alternative (sei_criar_documento_externo), leaving the distinction implicit.

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