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

Annotations already declare this is a non-readOnly, non-destructive write, so the bar is lower. The description adds genuinely non-schema behavior: the comment supports markdown, @mentions follow OpenProject's own rules, and the result is visible to the whole team — the last point is important for an agent judging disclosure risk.

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 short sentences, zero filler, with the core action stated first and the formatting/visibility caveats after it. Nothing could be removed without losing 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 write tool with no output schema, the description covers the essentials an agent needs to call it safely: format and audience. The remaining gap is the preview-then-confirm flow, which is present in the schema's 'cf' description, so overall completeness is high.

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 confirmation code, target id forms, and notification flag are already fully documented. The description adds only the markdown/@mention framing, which is marginal extra meaning for the parameters themselves, 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?

The description gives a clear verb+resource pair ('Comenta em um work package'), which is essential since the tool name 'cm' is opaque. It does not differentiate against the cryptic siblings (up, new, rel), so an agent must infer that 'cm' posts a comment rather than updating a field.

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

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

Usage is only implied by the verb: leaving a comment on a work package. There is no statement of when to prefer this over siblings like 'up' or 'new', and no mention of the approval/preview workflow that governs actually sending the comment (that constraint lives only in the schema).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds modest value by signalling that the payload is reference/context data (assignable people, project custom fields) rather than records, but it says nothing about result shape, size, or whether custom fields require a valid project id.

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

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

A single compact sentence with no padding, and the resource enumeration is front-loaded. It loses a point only because the enumeration substitutes for a clear leading verb, so the reader has to infer the action from the list.

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?

This is a low-complexity, two-parameter lookup tool with rich annotations and no output schema, so the description does not need to explain return values. Still, it leaves the core question — what the tool actually does with these categories and when to reach for it — unanswered, which is a clear gap even at this complexity level.

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% and both parameters are documented there, including the OPENPROJECT_PROJECT default and the 'todos' sentinel. The description merely re-lists the same enum categories and adds no syntax, default, or edge-case detail beyond the schema, so the baseline of 3 applies.

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

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

The description enumerates the resource categories available (account/instance, projects, statuses, types, priorities, members, versions, custom fields), which tells an agent what data domain this covers. However, it never states a verb — nothing says whether it retrieves, lists, or caches this context — and it draws no boundary against the cryptic siblings (ls, find, rd). The purpose is inferable but vague.

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?

There is no when-to-use guidance at all: no indication of when to call cx versus ls or find, no prerequisite that a project must exist, and no note that this is a bootstrap/metadata call typically made before other operations. The agent must guess from the enum alone.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds one genuinely useful piece of context — the output format matches 'ls' — but says nothing about default exclusions, pagination behavior, or search scope beyond what the schema field descriptions already give.

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 short sentences, scope first, cross-reference second — no filler. Its brevity edges toward under-specification rather than verbosity, but nothing is wasted.

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

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

For a six-parameter search tool with no output schema, the description leans entirely on the opaque cross-reference 'same output as ls', which an agent cannot resolve without calling another tool. Combined with rich schema coverage this is workable, but the return shape and result ordering remain unstated.

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 every parameter including the 'em' enum and 'fechados' default is already documented. The description only repeats that the input is text, adding no syntax, matching rules, or operator details.

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 Portuguese: searches ('Busca') work packages by text. That contrasts implicitly with the sibling 'ls' (plain listing), though the distinction is inferred rather than spelled out.

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

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

No explicit statement of when to use this over 'ls' or any other sibling; the only hint is 'Mesma saída do ls', which describes output, not selection criteria. An agent must guess that 'find' is for when you only have text rather than an id.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description's real contribution is disclosing the return format (compact pipe-delimited rows), which matters because there is no output schema. It still omits pagination/truncation behavior and the consequence of the default project scope.

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

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

A single front-loaded sentence with no filler; the purpose leads and the output contract follows. Every word 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 tool with ten optional parameters, filtering enums and pagination, plus no output schema, the description is thin: it covers 'what' and the row format but not routing against siblings or pagination semantics. The rich schema compensates partially, making this adequate but with clear gaps.

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

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

Schema description coverage is 100%, so all ten parameters including the filtro and ordem enums are already fully documented in the schema. The description adds no additional meaning about parameters, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Lista work packages") and adds the exact output shape, one line per WP with fields id|tipo|status|prio|resp|fim|%|assunto. It never names the obvious alternative (the sibling "find"), so an agent cannot tell from the description alone why it would pick ls over find.

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 contains no when-to-use or when-not-to-use guidance and points to no alternative tool. The only usage signal comes from the schema's filtro default ("abertos"), not from the description text.

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 establish write semantics (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds genuine behavior beyond them: default type resolution and the fact that the new work package becomes the current context. It omits the preview/confirmation prerequisite (cf) and the notification side effect, both of which matter for a create operation.

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

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

Three short sentences with the core action front-loaded and zero filler. Both the default-type rule and the context-switch effect are stated in a single clause each.

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 16-parameter mutation tool the description is very thin, though the schema and annotations carry most of the load. Nothing is said about what is returned (e.g., the new work package's id) or the confirmation-code workflow that the schema hints at, which an agent would want to know before calling.

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 every one of the 16 parameters already carries its own documentation, including the default-type rule for tipo. The description adds only marginal meaning beyond the schema, so the baseline 3 applies.

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

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

"Cria um work package" gives a specific verb and resource, and "O criado vira o atual" clarifies the post-creation effect. It does not name any sibling (up, cm, cx) to help an agent distinguish creation from updating or commenting, leaving that inference to the caller.

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?

"Sem tipo usa o tipo padrão do projeto" documents a fallback rather than when-to-use guidance, and "o criado vira o atual" implies that follow-up operations can target the new item implicitly. There is no explicit statement of when to prefer this over up (edit) or how the cf-confirmation flow sequences with the 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds mode-specific return content—summary fields/short description, full description/attachments/relations, comments/changes, and children—which is meaningful behavioral context given there is no output schema. It still omits error behavior and pagination details beyond the n parameter.

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

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

A single front-loaded sentence with no filler; the verb and resource come first, followed by a compact enumeration of modes and their contents.

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 low-complexity read tool with full schema coverage and complete annotations, the description covers the key mode behavior even without an output schema. Minor gaps remain around output structure and id/pagination defaults, but those are largely handled in the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the enum labels by defining what each mode returns, especially 'completo' (full description, attachments, relations) and 'atividade' (comments and changes), which materially clarifies the most important parameter.

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

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

States a specific verb ('Lê') and resource ('work package') and breaks the tool into four concrete modes with what each returns. It does not differentiate itself from the similarly named siblings (ls, find, etc.), so it falls short of 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?

Usage is implied by 'Lê um work package' and the mode descriptions help choose among resumo/completo/atividade/filhos. There is no explicit guidance on when to use rd instead of sibling tools such as ls or find, and no exclusions or prerequisites.

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, destructiveHint=false and idempotentHint=false, so the safety profile is partly covered. The description adds that removal is a supported mutation and hints at a textual relation grammar, but it omits the two-step preview/confirmation flow that the schema's 'cf' parameter implies, which is important behavior for a mutation tool.

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

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

Two short, front-loaded sentences with the action list before the grammar hint; nothing is padded. The final clause about reading the type from the id is slightly cryptic but still earns its place as a parsing hint.

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 an 8-parameter mutation tool with no output schema, the description covers the action space but leaves the confirmation-code workflow, what a listing returns, and permission prerequisites to the schema. It is adequate but does not fully carry the load the annotations leave open.

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 every parameter is already documented, giving a baseline of 3. The description adds a small amount of extra meaning by explaining that the relation type is parsed from the id string ('#12 bloqueia #15') and clarifying that 'precede' means the target starts only after the source.

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 (relações/dependências entre work packages) and the exact operations supported (listar, criar, remover), plus the relation families involved (bloqueia, precede, requer, relaciona). That is enough to distinguish it from generic siblings like ls/new/rm, though it never names them explicitly.

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

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

Usage is only implied through the enumerated actions; the description does not say when to prefer this tool over a generic link/update tool, nor does it state preconditions such as needing a prior listing to obtain the relation id for removal. Guidance exists but must be 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 destructiveHint=true, but the description adds information they cannot carry: deletion is irreversible because OpenProject has no trash, and child work packages are cascade-deleted. The mandatory confirmation step is also disclosed, which materially changes how the agent should sequence the call.

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

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

Three short sentences, each earning its place: destructive scope first, confirmation requirement second, routing alternative last. No restatement of the tool name or 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 destructive, no-output-schema tool this covers the essentials: permanence, cascade behavior, confirmation gating, and the safer alternative. The only gap is that the preview step which generates the 'cf' code is implied but not tied to a named 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 both 'cf' and 'alvos' are already documented in detail in the schema, including target formats and the preview-code flow. The description adds only an indirect hint ('Sempre pede confirmação') that the 'cf' token exists, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('Apaga work packages PERMANENTEMENTE') and immediately scopes the blast radius ('filhos também são apagados', no trash). It also distinguishes itself from the sibling 'up' for the closing use case, so an agent can route without opening either schema.

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

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

It gives both a when-not ('Para encerrar, prefira up com status fechado') and an explicit workflow expectation ('Sempre pede confirmação'), which tells the agent this is a two-step operation. The alternative path is named rather than 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?

Annotations declare readOnlyHint=false and destructiveHint=false, and the description reconciles this by making clear the tool also performs a read-style listing by default. Beyond that it adds little: it does not disclose the preview-then-confirm workflow that governs the write path (only the schema's cf parameter hints at it), nor permission or side-effect details for logging hours.

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

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

A single front-loaded sentence with the resource label first and the two modes clearly parallel-structured; no filler. It is perhaps slightly too compressed for a nine-parameter dual-mode tool, but nothing is wasted.

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

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

With nine optional parameters, two modes, and a write path, the description covers the mode split and defaults but omits the approval/confirmation prerequisite that is central to correct invocation, relying on the schema to surface it. With no output schema, it also says nothing about what listing returns or how logged entries are echoed.

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 explains acao, quem, periodo, data, horas, and cf thoroughly, including the confirmation-code approval requirement. The description largely restates the defaults that are already documented per-parameter, adding only the 'meus' mapping to quem='eu' implicitly.

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 (Horas) and two distinct operations — listar lançamentos and lançar horas em um work package — with their defaults, so an agent understands the tool's dual nature. It does not distinguish the tool from its cryptic siblings (ls, find, new, up), and the name 'tm' itself conveys nothing, so the description carries all the identification burden.

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?

Defaults are stated for both modes ('padrão: meus, esta semana' for listing, implying lancar otherwise), which implies when each branch applies. However, there is no explicit guidance on when to choose this tool over the many sibling tools, nor any statement of prerequisites or exclusions for the write mode.

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, destructiveHint=false and idempotentHint=false, so the description's main added value is the "only informed fields change" guarantee, which reassures the agent that unspecified fields survive. It does not surface the two-step preview/confirm requirement, the default notification side effect, or the fact that desc replaces rather than appends (that only lives in the schema).

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

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

Two sentences, front-loaded with the core action and immediately followed by the partial-update rule and the cm alternative. No filler, no repetition of 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?

For a 17-parameter mutation tool with full schema coverage and annotations, the description covers purpose, update semantics, and one key routing decision. The remaining gaps (confirmation flow, notification default, desc vs desc_add) are documented in the schema, so the definition is usable as-is.

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's field list loosely maps to parameters (status, responsável, prazo, prioridade, %) but adds no syntax or format detail beyond what the schema already specifies for alvos, cf, datas, or campos.

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?

"Altera campos de um ou vários work packages" gives a specific verb (update) and resource (work packages), then enumerates the editable fields (status, responsável, prazo, prioridade, %, campos personalizados). The opaque tool name "up" means the description must carry the whole burden, and it does so clearly. It does not broadly differentiate itself from siblings like new/rm/rel, though it does route one case to cm.

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?

"Só os campos informados mudam" sets the partial-update contract and "Para registrar progresso, prefira cm (comentário) a mexer na descrição" names an explicit alternative with the condition that selects it. What is missing is guidance on the preview/approval cycle (the cf parameter) and when multiple targets via 'alvos' should be used versus single edits.

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