Hilbana

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds genuinely non-obvious behavior: it is scoped strictly to workspaces you OWN as the paying account, and it fails when that set is empty. That ownership constraint is the key calling risk and it is disclosed. Return shape is described but no caveats on freshness/aggregation cost.

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?

Scope and ownership constraint are front-loaded, followed by the payload enumeration and trigger examples. The middle metric list is dense and runs long as a single sentence, but each item earns its place since no output schema exists to describe the return.

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 no output schema, the description carries the full burden of return-value disclosure and does so exhaustively, including per-workspace status, agent state, and the specific attention categories. Combined with the failure condition and ownership scoping, an agent has everything needed to decide and call 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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies no filtering or targeting arguments are accepted.

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 (aggregated overview of ALL owned workspaces) with a precise scope: the paying account, not workspaces you merely belong to. The enumerated payload (weekly closed comparison, in-progress, agent activity, per-workspace traffic light, attention items) makes it unmistakably distinct from list_workspaces and stats siblings.

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 trigger phrasing: questions like «¿cómo va la compañía?» or «¿qué está parado?». It also declares a hard precondition (fails if you own no workspace). It stops short of naming alternatives (e.g. workspace_stats for a single workspace), so routing is strong but not fully explicit.

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 write, non-destructive, non-idempotent, closed-world, so the safety bar is lower. The description still adds genuinely useful behavior context: the body is markdown with a specific mention format, and the author is derived from the API key rather than supplied. It does not state what is returned or whether duplicate posts are deduplicated.

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, purpose front-loaded, followed by two non-redundant details (markdown/mentions and key-bound authorship). No filler and nothing that duplicates the annotations or 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 two-parameter write tool with annotations and no output schema, the definition covers the essentials: what is created, where, in what format, and under whose identity. The one gap is the response — with no output schema, a note on whether the created comment (or its id) is returned would close the loop.

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 only 50% (issueId is documented in-schema with UUID/TEAM-123 rules, body is not). The description compensates by defining body semantics — markdown content plus the @[Nombre](user:UUID) mention syntax — which is exactly the missing half. It doesn't restate issueId resolution, but the schema already handles that.

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?

Specific verb+resource+target: adds a comment to an issue, with the body format and mention syntax spelled out. It clearly contrasts with read-only siblings like list_comments by being a write, but it never names update_comment or delete_comment as the alternatives, so sibling differentiation is only implicit.

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 the purpose and by the constraint that authorship is bound to the key's user (so no author can be chosen), but there is no explicit 'use this when' or exclusion versus update_comment/list_comments. The agent must infer that editing an existing comment belongs to update_comment.

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 (which only declare non-readOnly, idempotent, non-destructive, closed-world) by disclosing concrete side effects: started_at/completed_at/canceled_at are set according to the target state's type, no promotion to another state occurs, and moving to a 'started' state acquires a claim lock that release_issue frees. These are exactly the mutation consequences an agent needs 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?

Dense but front-loaded: the verb and target come first, then behavior, then the lock caveat. Every clause carries information, though the parenthetical and the compact multi-effect sentence require careful reading.

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

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

For a two-parameter mutation tool with annotations covering safety and no output schema, the description covers side effects, locking, and state-id sourcing adequately. The only gap is that the return value (e.g., the updated issue or its new timestamps) is never hinted at, since no output schema exists to carry it.

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 50%: 'id' is fully documented in the schema, while 'stateId' has no schema description. The description compensates by stating that stateId must be a workflow state obtained from list_workflow_states and that its type drives timestamp behavior, adding real semantic meaning beyond the bare string type.

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 a specific verb and resource ('Mueve una issue al workflow state stateId') and immediately identifies where the stateId value comes from (list_workflow_states). It also distinguishes the operation from the neighboring claim_issue / release_issue flow, so an agent can tell it apart without opening sibling 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?

Gives clear operational context: the state is applied as-is with no automatic promotion, and the valid source of stateId is named. It also warns that a 'started' type state claims the issue (same lock as claim_issue) and points to release_issue, which effectively routes the agent among alternatives. It stops short of an explicit 'use this instead of claim_issue when...' statement.

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 a non-read-only, non-idempotent, non-destructive mutation; the description goes well beyond them: it specifies the 409 failure mode, the exact blocker-state rule (blocked_by in a state other than completed/canceled/desbloqueante, with In Review as default example), and that the error names the blockers with their state. It also discloses global visibility to the UI and other agents, and covers the agentCloseState semantics governing task closure.

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

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

Front-loaded with the core action and immediately after it the failure conditions and the release alternative, so an agent can stop reading early. It is dense and every clause carries operational meaning, though the final agentCloseState sentence is somewhat cramped and reads as a separate concern.

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 no output schema, the description still tells the agent what matters: what gets written, what blocks success, how the failure reports itself, and how to undo the claim. For a one-parameter soft-lock mutation this is essentially complete; only the exact response body is unspecified, which is low stakes here.

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?

One parameter at 100% schema coverage, so the schema already explains that `id` accepts a UUID or a human-readable TEAM-123 key with case-insensitivity. The description adds no `id`-specific guidance, so baseline 3 applies; the agentCloseState (stateId, name, instruction) explanation is model/output context rather than a call parameter and does not raise this score.

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 ('Toma una issue') and immediately disambiguates it from a similar concept: 'lock blando, distinto del assignee'. It also names the exact fields it mutates (agentWorkingBy, agentWorkingSince), so the effect is unambiguous without consulting 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?

Explicitly says when to use it ('indicar que la estás trabajando AHORA') and names the counterpart tool for the inverse operation ('Libérala con release_issue'). It also enumerates the failure conditions and points to get_issue as where the state becomes visible, giving a full routing picture.

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 and readOnlyHint=false, so the irreversibility warning 'No se puede deshacer' reinforces rather than duplicates. The genuine added value is the authorization rule (author/key owner only) and the id provenance, which no annotation conveys.

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, front-loaded with the action, then permission, then id source, then irreversibility. Every sentence adds a distinct fact with 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?

For a single-parameter destructive mutation with no output schema, the description covers action, authorization, id provenance and irreversibility — everything needed to invoke it correctly. Only a hint about the response (success confirmation vs error on non-author) 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 0% and the single parameter is bare ('commentId': string), so the description must compensate — and it does by telling the agent to obtain the id from list_comments. It stops short of any format or example, which keeps it from a 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 verb and resource ('Borra un comentario'), which unambiguously separates it from add_comment and update_comment among the siblings. It does not explicitly name the alternatives, but the delete semantics leave no real ambiguity.

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 concrete preconditions: only the author (or the owner of the key) may delete, and the commentId must come from list_comments. It does not spell out when to prefer update_comment over deletion, but the operational context an agent needs before calling is present.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds important context beyond those annotations: the folder is removed but its contents are relocated, where they go, and that movedTo/count are returned. It does not cover permissions or irreversibility, but it substantially clarifies the destructive behavior.

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

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

The description is compact and front-loaded with the core behavior: deletion without content loss. The relocation rule and return values are stated efficiently, with no wasted 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?

For a one-parameter destructive folder operation with no output schema, the description covers the key side effect and return values well. It leaves gaps around parameter semantics and prerequisites, but the essential behavior an agent needs is present.

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

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

Schema description coverage is 0% and there is one parameter, but the description never explains what the id refers to or what format it expects. It implies a folder is targeted but does not compensate for the missing schema documentation.

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: deletes a document folder. Crucially, it distinguishes the operation from a content-deleting delete by explaining that documents and subfolders are moved to the parent or project root, so an agent understands the exact semantics 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 makes the deletion scenario clear but does not explicitly say when to use this versus alternatives like save_doc_folder or list_doc_folders. For a destructive action, more guidance about prerequisites or confirmation would help, though the use case is fairly obvious.

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 destructiveHint=true: it discloses the required admin role, the dry-run-by-default behavior, exactly what the destructive branch removes (issues lose the label) versus what it leaves untouched (automations, SLA rules, views keep pointing at the deleted label), and that the response warns the human to review them. replaceWith is described as applied before deletion, with template behavior specified separately.

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 action and the admin restriction, then the confirm/no-confirm contract, then the exceptions. It is dense but every clause carries operative information; the nested parenthetical enumerating impact fields makes it slightly harder to scan than it needs to be.

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 3-parameter mutation with no output schema, the description supplies the missing pieces: precondition (admin), safe-call pattern (call without confirm first), the shape of the impact report, and post-deletion state of dependent objects. An agent has enough to invoke it correctly and safely.

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

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

Schema coverage is 0%, so the description carries the burden and does: confirm is defined by its effect (no confirm = impact report only), replaceWith by its type (id of another label) and per-context behavior (issues reassigned, templates swapped). Only the `id` parameter is left implicit, though it is inferable from "Borra una label".

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?

"Borra una label de issues" gives a specific verb and resource and adds scope (issue labels, admin-only). It does not explicitly distinguish itself from the sibling delete_project_label, so the agent must infer the label-type split from the wording 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?

The description states clearly when deletion actually happens (only with confirm=true) and what the call does otherwise (returns impact so the caller can decide), which is the key usage decision for this tool. It stops short of naming an alternative tool for the project-label case, so it is strong context without explicit exclusions.

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

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

Although annotations already declare destructiveHint/idempotentHint, the description adds substantive context: the owner-only permission requirement, the dry-run behavior of omitting confirm (returns affected projects), and the consequence that projects are left unlabeled rather than deleted. That is exactly the beyond-annotation detail an agent needs before a destructive 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?

Four short clauses, each doing work: scope, permission, no-confirm behavior, confirm behavior. The safety-critical constraint (no confirm = no deletion) is front and center.

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-param destructive mutation with no output schema, the description covers authorization, dry-run behavior, and post-deletion state of related projects — everything needed to invoke it safely and 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 0%, so the description must carry the burden; it fully explains the semantics of 'confirm' (preview vs. actual deletion). The 'id' parameter is only implicitly identified as the project label's id, which is the remaining gap.

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

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

States a specific verb ('Borra') plus resource ('etiqueta de PROYECTO') and explicitly disambiguates from the near-miss sibling concept ('no una label de issues'). An agent can distinguish it from delete_label/list_project_labels 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?

Clearly says when it acts and when it doesn't: without confirm=true nothing is deleted, only previewed. It also states the authorization precondition ('Solo el dueño del workspace'). It stops short of pointing at an explicit alternative tool, but the guidance for use is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description adds nothing on permissions or side effects. It does disclose the returned field set, which is mild behavioral context, but says nothing about missing-document behavior or body truncation.

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 the verb and return shape front-loaded; no filler and nothing that could be trimmed 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?

With no output schema, listing the returned fields (id, título, body markdown, projectId, fechas) is genuinely valuable and covers the return contract. Minor gaps remain around error/not-found behavior and whether body is full or truncated.

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?

One required parameter (id) with 0% schema description coverage, so the schema contributes nothing beyond the type. The description names 'id' among the returned fields, implying the same identifier is the lookup key, but never states input format or that the id must reference an existing doc.

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 (lee) and resource (documento de proyecto completo), and the parenthetical field list distinguishes it from list_docs by signalling a full single-record retrieval. It does not explicitly name the read-only sibling it differs from, but the resource scope is unambiguous.

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: fetch one complete document, presumably by id, when you need the full body rather than the list view. No explicit when-to-use/when-not or reference to alternatives such as list_docs (for listings) or save_doc (for writes).

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 goes well beyond that by disclosing return semantics: agentWorking is null when the issue is free, each relation carries the other issue's state, and if the related issue is not visible only its identifier and state are returned. That last detail is genuinely useful permission-boundary behavior that no structured field conveys.

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 one long sentence, but it is front-loaded with the core value proposition and the enumeration is justified because there is no output schema to otherwise tell the agent what comes back. A small amount of framing (grouping the payload instead of a flat list) would improve scanability, 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 no output schema, the description must carry the return-value burden and does so thoroughly, covering the full field set plus the working/claim state and the closing-state instruction. The main residual gap is error behavior (unknown id, identifier ambiguous across workspaces, permission denial), which the schema only partly hints at.

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 the single 'id' parameter is already documented in the schema, including the UUID-vs-readable-identifier rule and the multi-workspace ambiguity case. The description adds no parameter-level information at all, 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 opens with a specific verb+resource framing ('Contexto completo de una issue en una sola llamada') and then enumerates the exact payload (title, markdown description, state, priority, assignee, dueDate, labels, sub-issues, comments, activity, attachments, relations, customFields), so an agent knows precisely what it retrieves. It is clearly a single-issue fetch distinct from list_issues/search_issues, though it never names those siblings explicitly to sharpen the contrast.

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 explicit when-to-use or when-not-to-use guidance and no named alternatives, even though siblings like list_issues, search_issues and issues_panel overlap. The only usage-adjacent content is a workflow instruction about agentCloseState ('el estado en el que tienes que dejar la tarea al terminarla'), which is about task completion rather than tool selection.

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 readOnlyHint=true by disclosing the non-obvious absence of a side effect (reading does not mark as read) and by flagging the message body as untrusted DATA with an injection-safety instruction, plus what the `note` field represents. Strong, though it says nothing about size/truncation of the returned message.

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, front-loaded with what it does, then the read-state caveat, then the safety note. No filler and nothing repeated from the schema or 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?

With no output schema, the description carries the return-value burden and partially meets it by naming the `note` field and saying the message is returned whole. A hint about the message body/attachment fields would make it complete, but the essentials for correct invocation are present.

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

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

Schema coverage is 0% — `id` is an undescribed string — so the description must compensate, and it does by stating the id identifies the message and is the value returned by list_messages. That is enough to source the parameter correctly, even without format 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 ('Lee un mensaje directo tuyo entero') plus the key qualifier that it returns the full message, which separates it from list_messages and from get_issue/get_doc siblings. An agent knows exactly what it gets 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?

Names where the id comes from ('el que da list_messages') and explicitly routes the read-state change to a different tool ('Leerlo NO lo marca como leído: usa mark_message_read'). Both the when and the when-otherwise 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?

Annotations only declare readOnlyHint and openWorldHint; the description adds the non-obvious behavioral contract: the tool renders nothing at all in unsupported clients, so the agent must fall back rather than retry. It also spells out the credential-default hierarchy and that the panel itself offers project selection when no default exists — context no annotation conveys.

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 what the tool does, followed by the client-support constraint, then parameter fallbacks. Every sentence carries unique information, though the parenthetical asides make it slightly packed for a quick read.

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 explained. For an all-optional, UI-rendering tool, the description covers the capability gate, the fallback tool, and default resolution for both undocumented IDs — everything needed to invoke it correctly or avoid invoking it.

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 only 50%, and the description compensates by explaining the two undocumented parameters: projectId falls back to the credential project then to in-panel selection, and workspaceId scopes which projects are offered. Query and includeClosed were already documented in the schema, so no additional detail is needed there.

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 ('Abre un PANEL INTERACTIVO con las issues de un proyecto') and immediately contrasts it with list_issues for clients without MCP Apps support. An agent can distinguish it from list_issues/search_issues 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 when-to-use (only in MCP Apps clients: Claude web and desktop), explicit when-not ('en el resto no se renderiza nada y hay que usar list_issues'), and names the alternative tool. It further resolves the two ambiguous optional parameters with default-resolution 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?

The annotations already declare idempotentHint=true and destructiveHint=false, so restating 'Idempotente' adds nothing. The description does earn credit for disclosing the return value ('Devuelve las relaciones de la issue origen') in the absence of an output schema, and for clarifying the asymmetric direction of 'blocks' vs the symmetric 'relates'.

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 compact sentences, front-loaded with the action and followed by the enum semantics and return behavior. The only wasted phrase is the redundant 'Idempotente', already covered by 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?

No output schema exists, and the description correctly states what is returned. Safety and idempotency are carried by annotations, so the remaining definition is sufficient for an agent to link two issues 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?

The schema documents both issue-ID parameters at 67% coverage, but leaves the 'type' enum undocumented. The description fills exactly that gap by defining what each of the three enum values means and which direction the relation runs, which is the semantic detail an agent needs before calling.

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

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

The description opens with a specific verb and resource ('Crea una relación entre dos issues'), which distinguishes it from read tools like get_issue. It never names unlink_issues, the obvious inverse sibling, so the differentiation is only implicit.

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 'Crea una relación', and the directionality of each 'type' value is spelled out. However, there is no explicit guidance on when to link versus when to use unlink_issues, or on preconditions such as both issues needing to exist in an accessible workspace.

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 genuinely useful behavior — chronological ordering and the shape of each comment (id, autor, body markdown, fechas) — but says nothing about pagination or result limits for long threads.

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?

One sentence, front-loaded with the action and resource, with the returned fields and ordering packed in without waste.

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 one-parameter read tool with no output schema, the description is nearly sufficient: it names the returned fields and the ordering. Only the absence of any pagination/volume note keeps it from being complete.

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

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

Schema description coverage is 100% and the single issueId parameter is fully documented there, including the UUID vs. TEAM-123 rule and case-insensitivity. The description adds no parameter detail beyond that, 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 (lee) and resource (hilo de comentarios de una issue) plus the fields returned, which separates it by name from the write siblings add_comment/update_comment/delete_comment. It never explicitly says how it differs from get_issue, so it stops 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 only implied: reading a comment thread is clearly what it does, but there is no statement of when to prefer it over get_issue, no exclusions, and no prerequisites. Nothing misleads, but the agent must infer the routing itself.

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 annotation, the description discloses the default exclusion of archived fields (and how to change it) and the fallback behavior when workspaceId is omitted (credential's workspace). It also encodes the value type mapping (checkbox=boolean, date=epoch ms, member=member ID), which is behavior an agent needs and annotations do not cover.

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 opening sentence is front-loaded with what the tool does and returns, and every subsequent sentence adds actionable information. However, the paragraph is dense with semicolon-chained clauses, which makes it slightly harder to scan than a punctuated list would be.

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 only two parameters, no output schema, and no annotation coverage beyond read-only, the description supplies the return shape, value types, default filtering behavior, and workspace resolution. Nothing an agent needs to invoke 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 0%, so the description carries the full burden, and it mostly does: workspaceId's optionality, default source, and discovery path are explained, and includeArchived's effect is stated. It could be marginally sharper on includeArchived's type (boolean), but the semantic intent of both parameters is clear.

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 los campos personalizados del workspace') and even enumerates the returned attributes (id, nombre, type, orden). No sibling tool lists custom fields, and the mention of save_issue/get_issue ties it to the correct workflow, so an agent can identify it 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 names the downstream tools that consume these IDs ('save_issue acepta customFields: { <fieldId>: valor } y get_issue los devuelve') and explains that this call is the prerequisite for reading or writing custom field values. It also points to list_workspaces for obtaining the optional workspaceId, so the selection context is complete.

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 context beyond that: results are limited to 'cycles visibles' (permission/visibility scoping), and with no workspaceId the credential's workspace is used silently — a non-obvious default that would otherwise cause surprise. It omits pagination or ordering behaviour.

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, zero filler. The output fields and purpose come first, then the parameter caveat with its default, so the most decision-relevant information 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?

For a single-optional-parameter read tool with no output schema, the description covers the return shape, the scoping rule, and the default-workspace behaviour. Nothing an agent needs in order 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 0%, so the description carries the full burden and does: it marks workspaceId as optional, defines it as the workspace to operate in, names list_workspaces as the way to discover valid values, and states the fallback (the credential's workspace) when omitted. That is everything needed to supply or skip the parameter correctly.

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 los cycles visibles') and enumerates the fields returned (id, número, proyecto, fechas), plus the reason to list them (assigning to issues). It also points to the sibling list_workspaces for the workspace dimension, though it never contrasts itself with save_cycle or list_issues, which are the nearest neighbours.

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 purpose clause 'para asignar a issues' implies when to reach for this tool, and 'list_workspaces los enumera' routes the agent for the workspace lookup. However, there is no explicit when-not guidance or exclusion (e.g. versus save_cycle for creating cycles), so usage is inferred rather than stated.

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 description's job is additive context. It delivers that by disclosing the tree model (parentId=null means root) and the workspace-defaulting behavior when workspaceId is omitted. It doesn't mention ordering, pagination, or depth limits, which keeps it from 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 what is listed and its fields, then the tree semantics, then parameter guidance. Dense but each sentence contributes; the cross-reference to list_docs/get_doc is useful rather than filler, though it slightly interrupts the parameter flow.

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?

There is no output schema, but the description compensates by naming the returned fields and the parent/child relationship, which is what an agent needs to consume the result. Remaining gaps are pagination/ordering and whether folder lists are capped, which are minor for a read-only list tool.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: projectId is an optional project filter, workspaceId is optional with a stated fallback to the credential's workspace and a pointer to list_workspaces for discovery. Both parameters gain meaning that the bare schema does not provide.

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 las carpetas de documentos') and enumerates the returned fields (id, name, projectId, parentId, position). It also positions itself against siblings by explaining that docs reference folders via folderId in list_docs/get_doc, so an agent can tell which tool returns what.

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?

Explains when each optional filter applies: projectId to scope to one project, workspaceId to pick the workspace, and it names list_workspaces as the way to enumerate workspaces. It stops short of explicit exclusions (e.g., 'use list_docs for documents themselves'), so it is clear context without full routing rules.

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 description's job is narrower. It adds real behavioral detail: folderId is null when the doc sits at the project root, and the workspace defaults to the credential's when workspaceId is omitted. Only pagination/result-size behavior is missing.

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 what is listed and what comes back, then handles the two parameters and the folderId null case in tight parenthetical asides. Every sentence carries information; only the parenthetical cross-references add slight density.

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?

There is no output schema, and the description compensates by naming the returned fields. It covers both optional parameters, the default workspace behavior, and the null-folder case, which is everything an agent needs 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?

Schema description coverage is 0%, so the description carries the full burden and does so: projectId is an optional project filter, workspaceId is the workspace to operate in with a stated default from the credential. Both parameters gain meaning not present in the bare 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 ('Lista los documentos de proyecto') and enumerates the returned fields (id, título, projectId, folderId, position), which distinguishes it clearly from get_doc (single doc) and list_doc_folders (folder tree).

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?

Explains that projectId is an optional filter, that workspaceId selects the workspace and falls back to the credential's workspace, and routes the agent to list_workspaces and list_doc_folders for related lookups. It does not state when to prefer get_doc or save_doc, but the usage context is otherwise explicit.

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 default 'live work only' filter, the fact that includeClosed is ignored when stateCategory is passed, and the fallback to the credential's workspace when workspaceId is omitted.

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 front-loaded: the default-exclusion rule and the override come first, followed by stateCategory semantics, then delivery/workspace. A couple of clauses repeat schema text (the includeClosed parenthetical) and the run-on structure is heavy, but nearly every sentence adds 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 6-parameter, no-required-parameter list tool with no output schema, the description covers filtering semantics, defaults, and credential scoping well enough to call it correctly. It does not describe the shape of returned issue records or pagination, which is a modest 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 only 17%, so the description must carry the load, and it largely does: it enumerates stateCategory values with meanings ('unstarted'/'backlog' = sin empezar, 'started' = en curso, etc.), defines delivery's three modes and its default, and clarifies workspaceId's fallback. Only teamId is left entirely unexplained.

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

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

States a specific verb+resource ('Lista issues') and the visibility scope ('visibles para la key') with optional team/project filters. It never names the obvious alternative sibling (search_issues), so an agent must infer whether to list or search, but the core purpose is unambiguous.

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 default exclusion of completed/canceled work, how to override it (includeClosed=true or stateCategory), and what delivery='own'/'delivered'/'all' means in context of a product projectId. It also routes to list_workspaces for workspaceId. The missing piece is guidance on when to prefer search_issues over this tool.

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 genuinely useful semantics on top by defining issueCount as only visible issues (permission-scoped counting) and stating that an omitted workspaceId falls back to the credential's workspace. It does not say whether the whole label set is returned or truncated, which is the remaining behavioral gap.

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, each doing distinct work: what is returned, where to write instead, and how the single parameter resolves. The purpose is front-loaded and the parenthetical field definitions are compact rather than redundant.

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 no output schema, the description correctly takes on the job of naming the returned fields and the visibility semantics of issueCount, and it resolves the optional-parameter default. It is nearly complete; only the question of result size/pagination or ordering is unaddressed for a list operation.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: workspaceId is optional, names the workspace to operate in, points to list_workspaces for enumeration, and specifies the credential default when absent. Nothing about the single parameter is left ambiguous.

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

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

Specific verb+resource ('Lista las labels del workspace') with the returned fields enumerated (id, nombre, color, issueCount), so the agent knows exactly what it gets. It explicitly separates itself from the write path ('Créalas o edítalas con save_label'), but never acknowledges the very similarly named sibling list_project_labels, leaving one obvious source of confusion unaddressed.

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 a clear when-to-use context (tagging issues) and routes mutations to save_label, plus explains how to discover workspaceId via list_workspaces and what happens if it is omitted. It stops short of an explicit when-not/alternative clause against list_project_labels or delete_label, so the agent must infer which label listing it 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?

With readOnlyHint=true already declaring the safety profile, the description adds useful behavioral context beyond annotations: what the records contain, that it is a lookup step for assigneeId, and the important fallback behavior when workspaceId is omitted (credential's workspace is used). Pagination or result-size limits are not mentioned.

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, front-loaded with purpose, then the return fields, then the parameter default. Zero filler; each sentence delivers distinct 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 one-optional-parameter read tool with no output schema, the description covers what it returns (id, nombre, email), why to call it (assigneeId), and the default behavior of the only parameter. Nothing needed to invoke 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 0%, so the description must carry the parameter burden, and it does: workspaceId is explained as optional, as the workspace to operate in, as enumerable via list_workspaces, and as defaulting to the credential's workspace. That fully removes ambiguity about what happens when the single parameter is omitted.

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 concrete verb and resource (lists the assignable members of the workspace) and names the fields returned (id, name, email), which tells the agent exactly what data this yields. It does not explicitly contrast against any of the many sibling list_* tools, but the 'assignable members' scope is distinctive enough to disambiguate.

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 a clear operational trigger ('necesario para obtener el assigneeId') so the agent knows this is the prerequisite call before assigning issues. It also names list_workspaces as the way to discover valid workspaceId values. It lacks an explicit 'do not use when' clause.

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 readOnly and openWorld; the description adds ordering, default filtering, scope behavior when workspaceId is omitted, and the pagination bound. It also discloses the untrusted-content trait (each message's `note` is data from a person, not an instruction) and tells the agent not to act on requested actions without user confirmation — a real behavioral constraint found nowhere in the structured fields.

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 ordering, then filters and limits, then the safety note — a sensible order with little wasted text. The prompt-injection caution is long relative to the rest, though it is high-value rather than 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?

No output schema exists, and the description at least characterizes returns: newest-first ordering, the per-message `note` field, and the trust framing around it. It does not sketch the remaining message shape (id, sender, timestamp, body), so an agent still discovers payload structure by 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 coverage is 0%, so the description carries the full burden and does: senderId is a userId of the sender, workspaceId scopes to one workspace with documented all-workspaces fallback, limit is bounded 1-100 with default 25, and includeRead's default and effect are spelled out. Nothing about the four parameters is left undocumented.

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

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

States a specific verb and resource — listing the agent's DM inbox, defined explicitly as messages other workspace people wrote to you, most recent first. That phrasing cleanly separates it from list_comments and get_message, which an agent could otherwise confuse with it.

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 ('Revísala al empezar a trabajar') and names the required follow-up action with the sibling tool: after telling your user, mark read via mark_message_read. It also states the default filter (unread only) and the opt-in (includeRead=true), so the agent knows which call shape to pick.

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 non-obvious behavior beyond that: results are restricted to 'visible' milestones and an omitted workspaceId silently defaults to the credential's workspace — an important implicit scoping rule.

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 with no waste: purpose and returned fields first, then the optional parameter and its default. Front-loaded and appropriately sized for a one-parameter read 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?

A read-only single-optional-param list tool with no output schema; the description covers purpose, returned fields, default scoping, and where to find workspace ids. 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 0%, so the description must carry the burden and does: workspaceId is optional, denotes the workspace to operate in, is defaulted from the credential when absent, and list_workspaces is named as the way to discover valid 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?

States a specific verb (lista) and resource (milestones) plus the scope ('visibles') and the returned fields (id, nombre, proyecto), and even the downstream purpose (asignar a issues). An agent can distinguish it from save_milestone or list_projects 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?

Explains the meaning and optionality of workspaceId and routes to list_workspaces for enumeration, plus states the fallback when it's omitted. It stops short of explicit when-not guidance against siblings, but the context for invoking it is clear.

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

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

Annotations already declare read-only and closed-world behavior. The description adds meaningful context: returned fields (id, nombre, color, posición, projectCount), cardinality ('Un proyecto lleva una como mucho'), assignment behavior, and workspace fallback from credentials.

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?

Information is front-loaded, starting with the core list action. It is dense and mostly earns its length, though the single long parenthetical paragraph could be easier to scan if broken into structured clauses.

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

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

For a simple read tool with one optional parameter and no output schema, the description covers purpose, sibling disambiguation, related write tools, returned fields, assignment rules, and parameter fallback behavior. No critical gap remains.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It fully explains 'workspaceId' as optional, identifies it as the workspace to operate in, points to 'list_workspaces' for enumeration, and states the fallback to the credential workspace.

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 las etiquetas de PROYECTO del workspace') and explicitly distinguishes it from issue labels via the sibling 'list_labels'. It also explains the practical purpose: sidebar project grouping.

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 says it is not for issue labels and points to 'list_labels' as the alternative. It also names related tools for creation ('save_project_label') and assignment ('save_project' with 'projectLabelId'), and explains the optional workspace fallback.

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 real behavioral context beyond that: results are limited to what the key can see, a project-scoped key collapses the result to one project, and workspaceId falls back to the credential's workspace. It doesn't discuss pagination or ordering, but the added visibility/fallback semantics are substantive.

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

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

Front-loaded with the core action and return fields, then usage, then the parameter note — a sensible order. The parenthetical field enumeration is dense but every item earns its place by telling the agent what it can read off the response. Slightly heavy for a single-parameter list tool, 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?

There is no output schema, so the description compensates by listing the returned fields and the meaning of the ambiguous ones (kind = initiative/product/null, projectLabelId → list_project_labels). Combined with the default-workspace behavior and the downstream projectId purpose, nothing needed 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?

Schema coverage is 0%, so the description must carry the parameter — and it does: workspaceId is defined as 'el workspace donde operar', with list_workspaces named as the way to discover values and the default behavior spelled out ('Sin él se usa el de la credencial'). That is everything an agent needs to decide whether to pass it.

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 los proyectos visibles para la key') and enumerates the returned fields (id, name, status, leadId, dates, color, icon, kind, projectLabelId), which distinguishes it from siblings like save_project or project_team_stats. An agent knows 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?

Explicitly names the downstream consumers ('Úsala para obtener el projectId que piden list_issues, list_docs, save_issue o save_doc') and points to list_workspaces for enumerating workspaces. It also explains the scoped-key edge case ('Con una key acotada a un proyecto devuelve solo ese'), leaving no ambiguity about when to reach for this tool.

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. The description adds real context beyond that: ordering, returned fields, that entries are human-authored (manual or AI draft), and the workspace fallback to credential. No contradiction with 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?

Dense but front-loaded: purpose, ordering, and returned fields come first, then the usage hint, then parameter notes. Every clause earns its place, though the parenthetical field list is slightly heavy.

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?

No output schema exists, so the description compensates by naming the return fields and ordering. Combined with the workspace fallback explanation, an agent has what it needs to call the tool 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 0%, so the description must carry the load, and it does: workspaceId is optional, defaults to the credential's workspace, and list_workspaces enumerates valid values. projectId scope is implied by 'de un proyecto' but not elaborated.

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 (list published status updates of a project), specifies ordering (most recent first) and even enumerates the returned fields. An agent can distinguish this from list_projects or project_team_stats 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 frames the use case (know how the project is going before starting work) and points to list_workspaces for the optional workspaceId. Lacks an explicit when-not or mention of alternatives beyond the workspace enumerator, but context is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: it returns an aggregate total in minutes alongside rows, and results are scoped to "las issues que alcanzas" (permission-scoped). It says nothing about pagination, limits, or ordering, which matters for a list 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-loads the core read plus the total-in-minutes return detail, then the filters, then the workspace default. Dense but every clause carries information; 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?

With no output schema, 5 params and 20% schema coverage, the description does a solid job on filters and the returned aggregate, but leaves out pagination/limits, ordering, and how multiple filters combine. An agent knows how to call it, not what volume of data to expect.

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 only 20% (only issueId documented), so the description carries real weight: it explains from/to are a date range in epoch ms, userId is the person filter, and workspaceId is the workspace with a defined fallback to the credential's workspace. That compensates well for three undocumented parameters, though exact filter combination semantics are not covered.

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 ("Lee el tiempo imputado") and adds the return shape ("el total en minutos además de las filas"). It is clearly a read operation, distinguishable from the sibling log_time, but it never names log_time explicitly as 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?

Usage context is implied rather than stated: filters are described as optional and the workspace default ("Sin él se usa el de la credencial") is explained, and list_workspaces is named for enumeration. However, there is no explicit when-to-use/when-not guidance versus log_time or the other list_* tools.

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. Beyond that, the description discloses the returned fields (id, nombre, type, team) and the credential-derived default workspace, which is genuine behavioral context. It does not mention ordering, pagination, or whether results are scoped per team.

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 compact sentences: what is returned first, why the tool exists second, parameter behavior third. No filler or redundant restatement of the name. Slightly denser than needed but every clause carries information the agent uses.

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

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

For a single-parameter, read-only listing tool with no output schema, the definition covers purpose, return fields, the one parameter, and the default. The only residual gaps are ordering/pagination of the list, which are minor for a small reference set.

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

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

Schema description coverage is 0% for the single workspaceId parameter, so the description must carry it — and it does: it marks the parameter optional, defines it as the workspace to operate in, explains the credential fallback, and routes the agent to list_workspaces for enumeration. That fully compensates for the bare 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 states a specific verb and resource ("Lista los workflow states") and enumerates what each entry carries (id, nombre, type, team), so the agent knows exactly what comes back. It also ties the tool to its downstream consumer (obtaining stateId for creating or changing issue state), which implicitly separates it from change_issue_state, though no sibling is named explicitly.

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

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

It gives a concrete trigger ("Necesario para obtener el stateId al crear o cambiar de estado una issue") and points to list_workspaces as the way to discover a valid workspaceId. It also states the fallback behavior when the parameter is omitted. There is no explicit "do not use when" guidance, which keeps it 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 already declare readOnlyHint and closed-world, so the safety profile is covered. The description adds real behavior the annotations cannot convey: the connection reaches ALL workspaces you are a member of, newly invited workspaces appear automatically with no new credentials or MCP servers, and the `default` flag means the credential's workspace used when none is specified.

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 front-loaded sentences: what is listed, why the scope is broad, then how other tools resolve workspaces. The third sentence is slightly tangential for a pure list tool but earns its place by clarifying default-workspace behavior used by sibling listing tools.

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 no output schema, the description still names the returned fields, and it covers scoping, the default-workspace semantics, and the auto-membership behavior. Nothing an agent needs in order to call this zero-parameter read tool 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, which is the baseline-4 case. The description's field list (id, nombre, slug, rol, default) describes outputs rather than inputs, but nothing is missing on the input side.

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 (workspaces) plus the exact scope: the workspaces reachable by this connection. It even enumerates the returned fields (id, nombre, slug, rol, default), so an agent knows what it gets without opening a schema that has no parameters.

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?

Explains the operational context clearly: entity-id tools (get_issue, add_comment) infer their workspace from the entity, while listing tools fall back to the default workspace. It stops short of explicitly contrasting with the nearest siblings (workspace_stats, account_overview), so it is clear context rather than full routing guidance.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real behavior on top: the default for startedAt (counts backwards from now) and the default for billable (true). It stops short of warning that repeated calls create separate entries, which is the main hazard implied by 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 core purpose and sibling contrast before parameters, and the sentences about record_run and billable each add distinct decision value. The restated 1–1440 range duplicates the schema bounds, the one clearly redundant fragment.

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

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

For a 5-parameter mutation tool with no output schema, the description covers defaults, constraints, and the main misuse case (deriving time from record_run). It leaves the `note` parameter unaddressed and says nothing about what the created entry looks like or whether it can be edited afterwards.

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 only 20%, so the description has to carry the load, and it mostly does: it explains minutes bounds, startedAt as epoch ms with a backfill default, and the meaning/semantics of billable. Only `note` is left completely undefined, which is a small but real gap given the low coverage.

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

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

States a specific verb+resource ("Imputa tiempo a una issue") and immediately scopes it with "SIN reloj", which separates it from start_timer/stop_timer siblings. It also explicitly rules out record_run as an alternative source of time, so an agent can place the tool 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 explicit when-to-use reasoning ("es la forma normal de que un agente registre lo que ha tardado, porque al terminar ya lo sabe") and an explicit when-not ("No deduzcas el tiempo de record_run") with the rationale about build waits. It also gives a decision rule for the billable flag (internal, non-client work).

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?

Adds concrete effects beyond the annotations: unread flag clears, the bell counter decreases, the call returns how many messages changed, and read=false reverses the operation. This is consistent with idempotentHint=true and destructiveHint=false. It does not cover partial-failure behavior when some ids are invalid.

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 target, then effects, then the reverse-mode caveat and scope. Dense but every clause carries information; slight chaining makes it a single long run-on sentence.

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 mutation with no output schema, it covers the state change, the return value ('cuántos cambió'), the reverse mode, and the ownership scope. Only edge-case behavior (invalid/foreign ids, batching limits) is left 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 coverage is 0%, so the description must carry the semantics: it identifies `ids` as direct-message ids from list_messages and defines `read=false` as unmarking, which is the non-obvious meaning of that boolean. Minor schema facts (maxItems 100, minItems 1) remain only in 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 and resource ('Marca como leídos tus mensajes directos') and ties the `ids` input to its source ('los de list_messages'), which distinguishes it from the read-only list sibling. An agent knows exactly what state change this produces.

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?

Explains where the ids come from (list_messages) and documents the reverse-mode alternative via read=false, plus the ownership constraint ('Solo toca los tuyos'). It does not spell out exclusions or when not to use it, but no sibling competes for this action.

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?

Adds substantial context beyond annotations: returns [] when the scope has no memory, requires a paid plan and non-project-scoped credential for cross-project use, marks foreign results with foreign=true, and defaults workspaceId to the default workspace. These are practical behavioral details an agent needs before invoking 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?

The purpose is front-loaded in the first sentence, and the remaining sentences each explain a parameter or behavior without filler. Although dense, every sentence carries useful invocation guidance.

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 no output schema, the description still explains the empty-result behavior and foreign-result marker, and it covers every parameter plus the credential/workspace requirements. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, but the description documents all five parameters: scope meaning, limit range/default, git_remote purpose, crossProject behavior, and workspaceId default/selection. It fully compensates for the missing schema descriptions.

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

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

States a specific verb and resource ('Carga las memorias más recientes de un scope') and clarifies it is queryless startup context, distinguishing it from search-style siblings. The phrase 'sin query' and the startup framing make its purpose unambiguous.

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 frames the tool as what the agent retrieves at startup for prior-session context, and gives conditions for crossProject and workspaceId use. It does not name sibling alternatives such as mem_search directly, but the 'sin query' contrast implies the boundary.

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 indicate readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable behavior beyond that: full untruncated content, workspace scoping, and null return for missing or cross-tenant records.

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 carrying a distinct and useful point: retrieval mode, scoping, and null behavior. It is front-loaded and free of 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?

The tool has no output schema, so the description must explain returns. It does so by stating full untruncated content and null for missing/cross-tenant memories, which is sufficient for a simple read-by-id tool, though return shape is not detailed.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It documents that id selects the memory and workspaceId overrides the default workspace, though it does not describe the id format.

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

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

The description states a specific verb and resource: read a memory by id. It adds distinguishing scope details, full untruncated content and tenant/workspace boundaries, which separates it from siblings like mem_search and mem_save.

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

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

It clearly explains the intended retrieval context: by id, scoped to the default workspace unless workspaceId is supplied. It does not explicitly name mem_search as the alternative for query-based lookup, so it falls short of full when-to-use guidance.

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

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

Goes well beyond the annotations: discloses that `replaces` deletes the superseded memory in the same step (the destructiveHint=true side effect made concrete), that scopes auto-register and can be merged via git_remote identity, that memories are shared team-wide, that credential project-restriction bounds scope visibility, and that the target workspace is resolved from a claimed issue and echoed in the response. This is exactly the extra context 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?

Core semantics are front-loaded and nearly every sentence carries a rule an agent needs (git_remote identity, merge behavior, replaces deletion, workspace targeting). It is dense and repetitive in places — the workspace/visibility point is restated at length in the final sentence, and long run-on sentences hurt scannability.

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 11-parameter mutation tool with no output schema and no schema descriptions, the description covers the non-obvious parameter interactions, side effects, visibility model, and even notes that the response reports the resulting workspace. Only the meaning of the `type` enum and expected `content` shape are unaddressed.

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 0% schema description coverage the description carries the full burden and explains scope, git_remote, scope_name/root_path, topic_key, replaces, and workspaceId with real semantics and decision rules. Gaps remain: the seven `type` enum values (decision/bug/convention/discovery/preference/fact/note) are never distinguished — only 'categoriza la observación' — and session_id/metadata get a one-phrase mention ('anotan la memoria').

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?

Opening line states a specific verb and resource ('Guarda una memoria del agente en un scope') and immediately defines what a scope is, so an agent can distinguish this write tool from the read-side siblings (mem_get, mem_search, mem_context) without opening any schema. The scope/type/topic_key explanation makes the resource model explicit.

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

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

Gives concrete conditional rules: pass git_remote whenever in a repo with a remote, except when a .hilbana/scope file exists (then use its contents instead); use `replaces` instead of leaving two contradicting versions; don't store machine-local details. It never names a sibling alternative such as checking mem_search first to avoid duplicates, which is the one obvious routing gap.

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 readOnlyHint/openWorldHint=false: discloses ordering (relevance + recency), the exact per-hit shape (snippet with <mark>, score, scopeKey/scopeName/foreign), empty-result semantics, per-project access control for guests, and the paid-plan + non-project-scoped credential prerequisite. It also warns that foreign hits are reference-only, not this repo's convention.

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?

Purpose and scope are front-loaded and no sentence is filler, but the single dense block piles parenthetical asides (the workspace default warning, the folder-name caveat) into one unbroken paragraph. Slightly long for what could be a lead sentence plus bullets.

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 six undocumented params, no output schema, and only two annotations, the description must supply both parameter meaning and return shape — and it does, including ordering, empty results, and hit field names. Nothing an agent needs 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?

Schema coverage is 0%, so the description carries the full burden and does: query (empty → []), scope (client's project folder name, stable), limit (1-50, default 25 — which also corrects the schema's meaningless numeric bounds), git_remote (output of `git remote get-url origin`), crossProject, and workspaceId including the default-workspace caveat.

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 in the first clause ('Busca en la memoria del agente ... full-text'), and immediately scopes it to a project/repo via `scope`, which separates it from broad siblings like mem_context or mem_save. An agent knows 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?

Gives concrete selection conditions: crossProject for workspace-wide lookup, git_remote when the local folder name differs from the clone, and workspaceId with a pointer to list_workspaces for enumeration. It stops short of an explicit 'use mem_get instead when you already have an id' style exclusion against siblings, so not a full 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 already declare write/not-readonly, non-idempotent, non-destructive, so the safety profile is covered. The description adds useful context that it writes to the current workspace like mem_save and that the response reports which workspace. It does not disclose what happens on repeated saves given idempotentHint=false (duplicate notes?), which is the main remaining behavioral gap.

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 compact sentences that front-load what the tool is and how it maps to mem_save, then the payload contents, then the workspace destination. Little waste, though the parenthetical field list is slightly dense.

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 7-parameter mutation with no output schema and zero schema descriptions, the description covers the core summary payload, session_id, and workspace behavior, so an agent can make a viable call. It is not complete: four scope/workspace parameters remain undefined and duplication semantics are 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 0% across 7 parameters, so the description must compensate and only partly does: it explains `summary` contents (objective, achievements, next steps, relevant files), marks `session_id` optional, and implies `scope` is repo/folder. The remaining root_path, git_remote, scope_name, and workspaceId are undocumented anywhere.

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 concrete verb and resource (save the end-of-session summary into scoped memory) and explicitly defines its implementation as a mem_save with type='note' and topic_key='session-summary'. This lets an agent distinguish it from mem_save and mem_context 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?

Clearly frames the use case: end of session, to resume the thread next session. It also names the underlying sibling (mem_save) and explains the relationship, though it never states when to call mem_save directly instead of this specialization.

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 a non-readonly, non-idempotent, non-destructive mutation; the description is consistent and adds real substance: atomicity/no-race guarantees, the dequeue ordering, and the null return when the queue is empty. This is exactly the kind of context annotations cannot express. It stops short of stating what happens on concurrent claims beyond 'sin carreras' or whether a claimed issue can be re-claimed.

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 core action is front-loaded in the first sentence, which is good, but the paragraph is dense and contains redundancy ('de una sola vez y sin carreras' restates 'atómicamente'). The agentCloseState segment occupies significant space for something that is not a parameter of this tool, diluting focus.

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 no output schema, the description correctly compensates by stating the return shape (the claimed issue with its context, or null). It covers defaulting behavior, scoping, and the follow-up release step. The phantom agentCloseState parameter and the absence of any note on repeated-call semantics leave small gaps for a non-idempotent mutation.

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

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

Schema coverage is 0%, so the description must carry all meaning, and it largely does: workspaceId is optional with a documented default (the credential's workspace) and a pointer to list_workspaces, and projectId is explained as a queue filter that, for PRODUCT projects, also pulls in tasks delivered by initiatives. The one flaw is that it describes agentCloseState (stateId, name, instruction) as if it were an argument, but that field is absent from the input schema, which can mislead an agent into passing it.

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: pulls the NEXT free issue from the 'ready for agent' queue and claims it atomically for the caller. The ordering rule (priority urgent first, then oldest) further pins down what 'next' means. It never names the sibling claim_issue, so an agent must infer the difference between claiming a specific issue and popping the queue.

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 lifecycle guidance: work the returned issue and release it with release_issue when done, and points to list_workspaces for enumerating workspaces. It also warns that the tool consumes only ONE workspace's queue and that without workspaceId it will not pull work from others. It does not say when to prefer claim_issue over this tool.

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 readOnlyHint=true and openWorldHint=false, the description discloses permissions behavior (guests get a permission error), default date window and timezone, and the caveat that persons only filters the activity section. That is meaningful behavioral context the annotations do not 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?

Dense but organized into three movements: what is returned, which filters exist, and formats/permissions. The output enumeration is long, yet each item names a distinct returned field, so little is wasted; a lead sentence naming the return categories would improve front-loading.

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 9-parameter, zero-schema-coverage, no-output-schema analytics tool, the description covers returned shape, filter semantics, defaults, enum behavior, and permission failure mode. An agent has everything needed to call it correctly without guessing.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: date formats and defaults, IANA tz, groupBy enum values with the special behavior of 'parent', and the fact that persons filters only activity. Only projectId and the exact semantics of milestoneId/labelId/cycleId are left implicit.

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 precisely that it returns the figures of one project's Team tab over a date range, and enumerates the returned blocks (KPIs, forecast, per-day, per-person, groupBy breakdown, activity list). The 'UN proyecto' scoping implicitly distinguishes it from workspace_stats and account_overview.

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 explains scoping filters, defaults for from/to (last 7 days) and tz (Europe/Madrid), and the membership precondition with the guest error. It does not explicitly route the agent away from workspace_stats, but the context for use is 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?

Beyond the annotations (which only say non-read-only, non-destructive, non-idempotent, closed-world), the description discloses that the run is stored in the issue's own run history separate from the human feed, that it is attributed to the API key's user, and that tokenCost is measured server-side by the plugin hook and must not be self-reported. That last point is real behavioral context that prevents silent data corruption; only the consequence of duplicate calls (multiple runs accumulate) is left implicit.

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 most important instruction, "call this always at the end of an issue", is front-loaded in the first clause. It is a single dense paragraph with no structural breaks, but nearly every sentence carries non-redundant information, including the tokenCost warning which is verbose but prevents a concrete error.

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 7-parameter mutation with no output schema and near-zero schema descriptions, the description covers purpose, timing, all meaningful parameters, storage location and the tokenCost pitfall. Missing pieces are minor: timestamp format, and no indication of what the call returns (e.g. a run id) which, absent an output schema, would have been worth one clause.

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 only 14% (just issueId), so the description must compensate, and it largely does: it explains the timing fields (startedAt/finishedAt), the result enum values (success/failure/cancelled), the summary's meaning, and that commitRef is optional and only for commits/PRs. The notable remaining gap is timestamp format – the schema types both as bare numbers with no hint whether they are epoch seconds or milliseconds.

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 uses a specific verb and resource ("Registra un 'run'" on an issue) and immediately enumerates what a run contains: start/end time, result, summary and optional commitRef. It also carves out the run history as separate from the human activity feed, which no sibling tool touches, so an agent can distinguish it from add_comment or log_time 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?

Timing is stated emphatically ("Llámala SIEMPRE al terminar de trabajar una issue") and the failure case is explicitly included ("y también si fallaste"), which is exactly the ambiguity an agent would otherwise hedge on. There is no explicit "when not to call" or named alternative, but the guidance on omitting tokenCost functions as a do-not instruction for one parameter.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds non-obvious context beyond that: exactly which fields are mutated and the permission model governing who may perform 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?

Two sentences, zero padding, with the action and its observable effect front-loaded and the permission constraint last. Every clause carries information the agent needs.

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 one-parameter mutation with full schema coverage and annotations covering idempotency and safety, the definition covers purpose, effect and authorization. It stops short of saying what error surfaces when an unauthorized caller attempts the release, a minor gap for a non-destructive, idempotent 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% and the single `id` parameter is thoroughly documented (UUID or human-readable TEAM-123, case-insensitive, UUID required on cross-workspace collisions). The description adds nothing about the parameter, 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 (release) on a specific resource (issue) and spells out the concrete effect: clearing agentWorkingBy/agentWorkingSince so the issue no longer shows as 'en curso' in the UI and to other agents. That effect statement cleanly separates it from siblings like claim_issue and change_issue_state.

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?

Names the authorization precondition (only the agent who claimed it, or a workspace admin), which tells the agent when the call will succeed. It implies the trigger (finishing/releasing a claimed issue) but does not explicitly name claim_issue or a state-change alternative as the contrasting tool.

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 readOnly=false, destructive=true, idempotent=false; the description adds genuinely new behavior: the server assigns the 'Cycle N' number per project, absent fields are left untouched while `name: null` clears, cycles in the same project may overlap in time, and the create response reports the resulting `workspace`. That is exactly the context 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-loaded with the create-vs-update rule, then per-field semantics, then sibling routing — a sound information order with no filler. It is dense (heavy semicolons and parentheses) and could be split into shorter sentences for scanability, but no sentence is expendable.

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

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

For a 5-param mutation tool with no output schema and no annotation detail, the description covers write semantics, field-omission behavior, server-side numbering, temporal constraints, and the shape of the create response (`workspace`). An agent has everything needed to call it correctly on 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 description coverage is 0%, so the description carries full burden — and it does: `startsAt`/`endsAt` are epoch ms with endsAt after startsAt, `projectId` is required on create but ignored on update, `name` is optional and null clears it. Notably it supplies create-time requirements that the schema's empty `required` list omits.

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 pairing ('Crea un cycle (sprint)... o actualiza uno existente') and immediately disambiguates the two modes by the presence of `id`. The parenthetical '(sprint)' plus the project scoping makes it distinguishable from save_issue and save_project without reading 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?

Explicitly routes the agent to siblings: 'Para meterle issues, usa save_issue con cycleId' and 'Usa list_projects/list_cycles para los ids'. It also states the mode-selection rule (no id = create, id = update) and the invariant 'Un cycle NO se mueve de proyecto', so the caller knows what this tool will not do.

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 flag destructiveHint=true and non-idempotent behavior, and the description adds real context beyond them: the create/update duality, that the workspace is derived rather than supplied, that the create response reports the resulting workspace, and the distinction between null and omitted folderId. It stops short of warning that an update with a new body overwrites the existing markdown, which would have closed the destructive-behavior gap for an agent.

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 create-vs-update rule leads, and each subsequent clause covers a distinct decision the caller must make (required fields, workspace derivation, folder behavior). No sentence is restated or filler, even though the description is dense.

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 five-parameter mutation tool with no output schema, the definition covers the operation modes, both required-field rules, all optional parameters, and even the one return value an agent needs (the workspace assigned on create). Nothing needed to invoke it correctly 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 0%, so the description has to carry all five parameters and it does: id toggles create vs update, title is mandatory, body is markdown, projectId is mandatory on create and sourced from list_projects, and folderId's null vs omitted semantics are spelled out. This effectively compensates for the absent schema documentation.

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 first sentence names a concrete verb and resource and splits the tool's two modes precisely: create when no id is supplied, update when an id is. It also routes the agent to the correct siblings (list_projects, list_doc_folders) so save_doc is distinguishable from save_doc_folder and save_project.

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 conditions are given for every branch: projectId is required only when creating, folderId null means root while omitting it means leave in place, and moving a document requires calling with id + title + folderId. The helper tools needed to obtain projectId and folderId are named outright.

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

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

Beyond the annotations, the description discloses partial-update semantics ('lo que se omite no cambia'), that parentId=null moves the folder to the project root, and the cycle constraint preventing a folder from being moved into itself or a subfolder. It does not mention permission requirements or what the call returns, but it gives substantive behavioral context that the destructiveHint/idempotentHint flags alone do not 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?

The create/update distinction is front-loaded, then per-mode parameter rules, then constraints, then the sibling pointer. Every sentence carries information; nothing is redundant.

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 0% schema coverage and no output schema, the description covers modes, required/optional parameters, and key constraints. The remaining gap is that it does not indicate what the call returns (e.g. the created folder's id), which matters for a create operation.

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

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

Schema description coverage is 0%, so the description carries the full load and does so: id selects create vs update, name is required on create and renames on update, projectId scopes creation, and parentId moves the folder with null meaning root. Nearly every parameter's meaning and conditional requirement is explained.

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 and enumerates both operational modes: creating a doc folder when there is no id, renaming/moving it when an id is supplied. It also explicitly separates itself from the sibling save_doc, which is the tool used to place a document inside a folder.

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 states when to use each mode (sin id vs con id), which parameters are mandatory per mode (projectId and name on create), and which are optional (parentId). It also names the alternative tool for a related but different task (save_doc with folderId) and notes the self-move restriction.

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?

Adds high-value mutation semantics not present in annotations: changing projectId wipes the milestone unless milestoneId is sent in the same call, changing productId clears its milestone, and permission nuance (product-only writers may change productMilestoneId but not content). Also explains workspaceId resolution on create vs update. It is consistent with destructiveHint=true and readOnlyHint=false, so no contradiction, though it never says what the create response body looks like beyond naming the workspace.

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

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

The create/update split is front-loaded and the caveats are attached to the fields they affect, so a reader can stop early. It is dense and long for a description, with some repetition around milestone/product milestone clearing, but nearly every sentence carries a rule an agent cannot infer elsewhere.

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 23-parameter, zero-required, no-output-schema mutation tool this is a solid briefing covering the dangerous cross-field interactions and ID resolution. It falls short of complete because six parameters are never mentioned and the expected create-time payload/response shape is only gestured at ('la respuesta dice en qué workspace quedó').

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 only 4%, so the description must carry the load and largely does: description, agentContext, definitionOfDone, verifyCommand, assigneeId, projectId/milestoneId relationship, dueDate (epoch ms, null clears), parentId, labelIds vs addLabelIds/removeLabelIds, agentReady, productId/productMilestoneId and workspaceId all get meaning. Gaps remain for title, teamId, stateId, estimate, priority and customFields, which get no explanation at all despite being untyped in 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?

Opening sentence states a specific verb+resource ('Crea una issue... o actualiza una existente si se pasa id') and the discriminator between the two modes is the presence of `id`. It also marks the atomic TEAM-N numbering, distinguishing it from a plain create from the siblings.

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: pass `id` to update, omit it to create; use list_workflow_states/list_labels/list_milestones/list_members/list_custom_fields to resolve IDs; create milestones with save_milestone; agentReady feeds the next_ready_issue queue without changing state. Exclusions and prerequisites are stated rather than 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?

Adds substantial context beyond the annotations: default gray color, case-insensitive duplicate detection that returns the existing label with created=false, and the requirement to be a full workspace member rather than a guest. These behavioral details are exactly what an agent needs for a mutation tool with no output 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?

The description is compact and front-loads the create/update distinction, with important constraints following in a logical order. It is slightly dense with multiple clauses, but nearly 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?

Covers the mutation's scope, required and optional fields, default behavior, duplicate handling with a created=false return signal, and permissions. Given there is no output schema, this is complete enough for an agent to call the tool correctly without guessing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: id toggles create vs update, name is required on create, color is optional with hex format and a default, and workspaceId is optional. All four parameters are meaningfully explained.

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: creates a label when no id is given, or renames/recolors it when an id is present. It also disambiguates scope by stating labels are workspace-wide, not project-level, which separates it from save_project_label and delete_label siblings.

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 create vs update based on the presence of id, and redirects label assignment to save_issue with labelIds/addLabelIds. It does not explicitly name save_project_label as the alternative for project-scoped labels, though the workspace-scope sentence implies that 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 destructiveHint=true and idempotentHint=false, so the mutation profile is covered; the description adds what those annotations cannot: absent means leave untouched while null clears description/targetDate, and the workspace is derived from the project rather than passed in. That is exactly the 'what gets destroyed and how' context the annotations leave open.

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 create-vs-update distinction, then constraints, then the alternative tool; every sentence carries information. It is dense and uses caps for emphasis, which is efficient but leaves little slack for scanning.

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

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

With no output schema, the description still tells the agent what the create response returns (the resulting `workspace`), and it resolves the misleading zero-required-parameter schema by stating create-time requirements. Only the undocumented `position` parameter keeps it from being fully complete.

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

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

Schema description coverage is 0% and required is empty, so the description must compensate — and it does, marking projectId and name as mandatory on create, giving targetDate an explicit format (epoch ms), and defining the absent-vs-null contract. The only gap is `position`, which appears in the schema but is never explained.

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

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

The description states a specific verb and resource and splits the two modes cleanly: create when there is no id, update when there is one. It also names the adjacent tool (save_issue with milestoneId) so the agent can tell this apart from issue-level operations 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 explicit routing: use list_projects/list_milestones to obtain ids, and use save_issue when the goal is to attach issues to a milestone. It also states a hard constraint (a milestone never moves between projects) that closes off a plausible but invalid usage path.

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?

Adds real behavioral context beyond the annotations: absent fields are left untouched, explicit `null` clears fields where allowed, and `kind` is irreversible once set (and must not be set on the General project). It also discloses the fallback behavior for workspaceId/teamId and that the response reports which workspace was used. Not stated: permission requirements or what the update overwrites on failure.

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 correctly: create-vs-update routing first, create requirements second, update field catalog third, with workspace/team fallbacks last. It is dense and repeats enum values already present in the schema, but the length is defensible for an 18-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?

Covers the create path, the update path, field-clearing semantics, supporting lookup tools, and the fallback/response behavior for workspace and team, which is essentially everything needed to call it correctly. Gaps are minor: no error/permission behavior and no guidance on ordering or required state before update.

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 0% schema description coverage across 18 parameters, the description carries the full burden and does so — it defines date format (epoch ms), color format (hex #rrggbb, null = neutral), icon format (emoji or 'lucide:Name'), the groupBy options, the null-vs-absent clearing contract, and the permanence of `kind`. Only the contents of propertyOrder/visibleColumns arrays remain loosely specified.

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 pair and immediately splits the two modes: create without `id`, update with `id`. The field list and the `kind` distinction make it unambiguous against siblings like save_issue or save_project_label.

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 `list_projects` to obtain the id, `list_members` for leadId, and `list_project_labels` for projectLabelId, plus states create-vs-update selection via presence of `id`. It stops short of saying when *not* to use this tool (e.g. label/team creation), but the prerequisites are unusually well 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?

Goes well beyond the annotations: discloses case-insensitive name dedup returning the existing label with created=false, the default color (#6e7781), that new labels go to the end of the list, plan-based quota limits, and the owner permission gate. There is a mild tension with idempotentHint=false (repeated creates collapse to the same record), but the tool's update path is genuinely non-idempotent, so this is a nuance rather than a 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?

Front-loaded with the create-vs-update distinction and the wrong-sibling warning, with no filler sentences. It is dense to the point of being paragraph-heavy — the ALL-CAPS emphasis and semicolon chaining make it slower to scan than it needs to be.

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 4-param mutation tool with no output schema and destructiveHint=true, the description covers what gets created or changed, the dedup return signal, quota constraints, permissions, and the downstream linking call. 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 0%, but the description compensates fully: name is mandatory on create, color is optional with hex #rrggbb format and a documented default, workspaceId is optional, and id selects update mode. It also supplies per-mode requiredness that the schema (0 required) 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?

States a specific verb+resource pair with explicit upsert semantics: creates a PROJECT label when no id is given, renames/recolors it when an id is given. It also disambiguates from the very similarly named save_label (issue labels) and situates the resource as workspace-wide sidebar groups.

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 the exact branching rule (no id = create, id = update), names the near-miss sibling save_label as explicitly NOT this tool, states the owner-only permission prerequisite, and routes the follow-up action (assign a project to the group via save_project with projectLabelId).

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 adds the real behavioral context: Spanish stemming dictionary, relevance ordering, default limit of 25, credential-derived default workspace, and notably that identifier searches without workspaceId span all workspaces and may return duplicates across rows. That cross-workspace side effect is exactly the kind of trait an agent cannot get from structured fields.

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 does and what it returns, then progressively more specific parameter rules, with no filler sentences. It is dense and long, and the trailing explanation of why identifiers are not unique across workspaces restates at more length 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?

Four parameters, no output schema, and the description still documents the return shape (issue fields, snippet with <mark> tags, rank, embedded customFields so no per-issue fetch is needed), which removes the need for an output schema. Nothing an agent needs in order to call it correctly appears to be 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?

With 0% schema description coverage the description carries the full burden, and it does: query (full-text or exact TEAM-N), limit (1-100, default 25), workspaceId (default from credential; list_workspaces enumerates), and customFields with the {fieldId, op, value, value2} shape plus per-type operator sets and value formats (userId for member, epoch ms for date, value2 for between, AND-combination with query). Minor caveat: its stated limit range of 1-100 is stricter than the schema's integer bounds, a small inconsistency worth noting.

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 ('Busca issues por FULL-TEXT') and pins down the exact mechanism (Postgres tsvector, diccionario español, ts_rank) plus what each result carries, which is far more than the name conveys. It never names the sibling it competes with, however: the note 'query vacía + customFields = listado filtrado' effectively overlaps list_issues without telling the agent which to prefer.

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 conditional guidance inside the tool: full-text via query, narrowing via customFields, empty query + customFields as a filtered listing, and exact-identifier lookup. It also explains the cross-workspace consequence of searching a TEAM-N without workspaceId. It stops short of stating when NOT to use it (e.g., retrieving a single issue by id, or browsing with list_issues).

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 generic mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=false); the description adds the delivery mechanism (bell + notification center + agent inbox via list_messages), the hard 10000-character and text-only constraints, and an hourly send rate limit with batching advice. It also clarifies that the recipient reads it as a human message, which affects how content should be phrased — none of this is recoverable from 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?

Front-loaded with purpose and delivery outcome, then constraints, then optional param — a sensible order with no filler sentences. It is dense (a single long block covering five distinct topics) and the mixed Spanish/English against an English tool name is a minor friction, but nothing is redundant.

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 3-parameter, no-output-schema write tool this covers everything an agent needs: recipient resolution, content format limits, rate-limit behavior, workspace scoping, and how to retrieve the resulting message. No output schema exists, so the explicit pointer to list_messages/get_message adequately covers the return side.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: `to` accepts either a userId obtained from list_members or the email of a workspace MEMBER, `body` is markdown with auto-linked identifiers (DRAPPS-123) limited to text and 10000 chars, and `workspaceId` is optional with a documented default from the credential. Every parameter gains meaning absent from the bare string types.

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 ('Envía un mensaje directo a otra persona del workspace') and immediately states where the recipient sees it, routing it clearly away from list_messages which it names as the read counterpart. An agent can distinguish this from add_comment and list_messages 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 concrete when-not rules: guests do not receive messages, you cannot write to yourself, and it explicitly is not a channel for commanding other agents. It names the helper tools for each sub-task (list_members for userIds, list_workspaces for workspaceId) and instructs batching due to the hourly cap.

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 (non-readonly, non-idempotent, non-destructive), the description discloses the critical side effect: only one timer can be active per person and starting a new one stops the old one. It even describes what the response reports (which timer was stopped and how many minutes it logged), which is real 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?

Purpose is front-loaded in the first clause, followed by side effects and the alternative tool. The sentence about stopping the previous timer is slightly convoluted in phrasing but every sentence carries distinct, necessary information; nothing is redundant.

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 mutation tool with no output schema, the description covers the action, the single-active-timer constraint, the stopping behavior, the return content, the billable default, and the log_time alternative. 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 50%: issueId is richly documented in the schema, while billable has no schema description. The description compensates by defining billable's default (true) and its business meaning (set false for internal work not billed to the client), so both parameters are usable. It stops short of explaining issueId, but the schema already covers it well.

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?

"Arranca TU reloj en una issue" is a concrete verb+resource, and the description immediately distinguishes this from log_time (for work already done) and implicitly from stop_timer. An agent knows exactly what this tool does and what it is not before 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?

It gives an explicit rule: use start_timer for live tracking, use log_time when the work is already finished and no clock is needed. It also tells the agent that starting a timer while another runs will stop the previous one, which is the key decision-relevant precondition.

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, idempotentHint=false, so the safety profile is covered. The description adds that it returns the minutes and issue and constrains to a single timer, but it does not disclose behavior when no timer is running or whether a repeated stop errors out.

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?

Compact and front-loaded: purpose and return values come first, followed by the two optional parameters. No filler, though the parenthetical and workspace tangent are dense in one run.

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

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

For a two-optional-parameter mutation with no output schema, the description covers the key return (minutes + issue) and both parameters. It stops short of describing failure modes (no active timer) but is otherwise sufficient to invoke correctly.

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

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

Schema coverage is 0%, so the description must carry both parameters, and it does: `note` is explained as an optional record of what was done, and `workspaceId` as the target workspace with a pointer to list_workspaces and a stated default to the credential's workspace. This meaningfully compensates for the empty schema.

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

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

States a specific verb+resource ('Para TU reloj' / stop your timer) and adds that it returns the imputed minutes and the issue, which clearly distinguishes it from start_timer. The parenthetical 'el único que puedes tener' clarifies the single-timer constraint. It does not explicitly name the sibling it excludes, keeping it just below 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 (you stop a timer you previously started) but there is no explicit when/when-not guidance or comparison to start_timer or log_time. The note 'list_workspaces los enumera' does helpfully route the agent for the workspace dimension, but that is parameter guidance, not tool-selection guidance.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, and the description is consistent with them ('Borra'). It adds useful context about where relationId comes from, but says nothing about reversibility or error behavior when the relation is missing.

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?

One sentence, front-loaded with the verb and resource, with the parameter clarification parenthetically attached. No wasted text.

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

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

For a single-parameter destructive mutation whose annotations already declare the safety profile and idempotency, the description covers the essentials: what is destroyed and how to obtain the identifier. Only failure-mode behavior on an unknown relationId is unaddressed.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does so well: it defines relationId as 'el campo id de cada relación' and tells the agent to source it from get_issue/link_issues. It stops short of stating the expected format (string vs. numeric id) or example value.

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?

Uses a specific verb ('Borra') plus the affected resource ('una relación entre issues'), so the operation is unambiguous. The parenthetical reference to get_issue/link_issues implicitly separates it from its sibling link_issues, but it never explicitly contrasts 'delete vs. create relation'.

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: the agent must infer it should call this to remove an existing relation and link_issues to create one. It does not state when-not to use it (e.g. that link_issues is the inverse) or what happens if the relation does not exist.

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, idempotentHint=true and readOnlyHint=false, so the description earns credit for adding the auth rule and the side-effect note 'Editar no vuelve a notificar'. It stops short of saying the previous body is overwritten/lost, which is the main destructive consequence the annotations flag.

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, front-loaded with the action and followed by the authorization, id-source and notification constraints. No wasted text.

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

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

For a two-parameter mutation with annotations and no output schema, the definition covers action, permissions, id sourcing and notification behavior. Adding an explicit note that the prior body is replaced would close the remaining gap against destructiveHint=true.

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

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

Schema coverage is 0%, so the description must carry the load: it explains that body is markdown with mention support and that commentId values come from list_comments. Only the id format/precondition is left implicit, which is a small gap for a two-parameter tool.

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 ('Edita el body ... de un comentario') and scopes the editable surface to the body, noting it is markdown and supports mentions. That distinguishes it cleanly from add_comment and delete_comment in the sibling list without opening 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?

Explicitly states the authorization condition (only the author / the key owner) and where the ids come from (list_comments). It lacks an explicit contrast with delete_comment or add_comment, but the usage context is clear enough to act on.

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 description's job is to add context and it does: workspace-membership requirement, default range and timezone, and the exact computation method for the forecast (linear extrapolation, Mon–Fri, no holidays). The one thing it omits is expectation-setting on cost or pagination for a potentially heavy aggregation, which keeps it from 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?

It is appropriately sized for a parameterless-but-output-heavy tool and the resource is front-loaded, but the body is a single sprawling run-on sentence that chains output fields, computation method, defaults and auth into one breath. A few line breaks or bullets would make the return payload far easier to scan.

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?

There is no output schema, yet the description spells out the returned structure in detail (per-project task counts, pace, forecast, activity per day and person). Combined with full parameter documentation and the membership precondition, an agent has everything needed to call and interpret 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?

Schema coverage is 0%, so the description must carry all four parameters and it does: from/to are YYYY-MM-DD with a stated default of the last 30 days, tz is IANA with a Europe/Madrid default, and workspaceId is explicitly optional with its fallback (the credential's workspace) and a pointer to list_workspaces. Nothing is left undocumented.

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

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

The description opens with a concrete resource and scope ('Cartera de proyectos del workspace') and then enumerates exactly what it returns per project (task counts by state, pace, forecast, closures, activity). It is unambiguous what the tool produces. It stops short of 5 because it never distinguishes itself from the similar sibling project_team_stats, so an agent must infer which aggregation level each provides.

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 context is implied rather than stated: 'Solo para miembros del workspace' gives an access precondition and the defaults (last 30 days, Europe/Madrid) make the call shape obvious. But there is no explicit 'use this when…' guidance and no routing to or away from project_team_stats, which is the nearest alternative.

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