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

The description explains that text is sent in plain text and converted to the API format preserving line breaks, which adds some behavioral context. However, with no annotations provided, the description does not cover potential side effects, auth requirements, or error handling (e.g., what if the issue doesn't exist).

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 consists of two concise sentences. The first states the core purpose, and the second adds a relevant processing detail. No unnecessary words or redundancy.

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

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

Given the lack of annotations and output schema, the description is somewhat minimal. For a write tool, it could mention success indicators (e.g., returns comment object) or common constraints. However, for a simple comment-adding operation, it provides the essential information.

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

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

The input schema already has 100% coverage with descriptions, but the description adds value by clarifying that the body is processed as plain text with line breaks preserved. This augments the schema's generic 'Texto del comentario' with practical formatting 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?

The description clearly states the action (adds a comment) and the resource (Jira issue). The verb 'añade' and resource 'comentario a un issue' are specific, and the tool is easily distinguishable from siblings like jira_create_issue or jira_update_issue.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., when to add a comment vs. a worklog). There are no explicit when-to-use or when-not-to-use instructions, leaving the agent without context for 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?

No annotations exist, so the description carries full burden. It mentions that the response includes how Jira interpreted the time in seconds due to site configuration, which adds some behavioral context. However, it does not disclose destructive potential or authentication requirements.

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

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

The description is a single sentence that effectively conveys purpose and a key behavioral note. It is front-loaded and concise without unnecessary 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?

Tool has 4 parameters with full schema coverage and no output schema. The description adds some context about the response but omits details about idempotency or side effects. It is adequate but not comprehensive for a mutation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining that the response includes interpretation of time in seconds, which goes beyond schema definitions. This provides helpful context for understanding the tool's output.

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 'Registra' and identifies the resource 'tiempo trabajado en un issue de Jira'. It clearly distinguishes from sibling tools like jira_get_worklog (retrieve logs) and jira_my_work.

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 does not provide any guidance on when to use this tool versus alternatives like jira_get_worklog or jira_my_work. It lacks context for appropriate usage.

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

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

With no annotations, the description carries full burden. It explains validation before sending, dryRun behavior, custom field flexibility, assignee formats, and estimate format. Lacks explicit mention of return value or rate limits, but sufficient for a create 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?

The description is moderately long but efficient, with logical flow. Every sentence adds value, though minor redundancy could be trimmed.

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 12 params and nested objects, the description covers validation, dryRun, parameter specifics, and references sibling tool for field lookup. Lacks explicit return value, but overall complete enough.

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

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

Schema coverage is 100%, but description adds value by explaining custom fields by name/ID, assignee accepts email/name/accountId, estimate format examples, and parent required for subtasks.

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 clearly states it creates a Jira issue, validates against real schema, and mentions dryRun. It distinguishes from siblings like jira_update_issue and jira_get_issue.

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 recommends consulting jira_issue_fields beforehand and explains the dryRun option for testing. It implies when to use but does not explicitly state when not to use.

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

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

The description discloses that deletions are permanent and lists the types of items that can be deleted. However, it lacks details about required permissions, potential side effects, or whether the operation is idempotent. Given no annotations are provided, this is adequate but leaves some behavioral aspects opaque.

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 extremely concise, using two sentences to convey all necessary information without any superfluous words. It starts with the primary action and then provides critical usage guidelines.

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

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

Given the tool's simplicity (delete specific items) and the fact that all parameters are fully documented in the schema, the description covers all essential aspects: what it does, what it cannot do, sources for IDs, and a pointer to an alternative. No output schema is needed.

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

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

The input schema covers all three parameters with descriptions, and the description adds value by explaining where to find the IDs for each type and clarifying that issueKey is mandatory for comments and worklogs but not for links, which goes beyond the schema.

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

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

The description clearly states that this tool permanently deletes comments, worklogs, or links, and explicitly distinguishes it from deleting issues by referencing jira_transition_issue for that purpose. It also specifies where to obtain identifiers for different types.

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

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

The description provides explicit guidance on when to use this tool (for deleting comments, worklogs, links) and when not to use it (not for issues). It also suggests an alternative tool (jira_transition_issue) for retiring issues and mentions how to obtain IDs from jira_explain_issue or jira_get_worklog.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns multiple pieces of context in one call and can include extra fields. This is sufficient for a read operation, though it could mention that it is non-destructive or note any rate limits.

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

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

The description is two sentences, front-loading the main purpose and then adding the extra fields capability. Every sentence adds value, and there is no redundancy or unnecessary detail.

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 no output schema, the description adequately explains the return structure (issue details, parent, subtasks, linked issues, comments, transitions, extra fields). It is complete for a single-issue explain tool, though it could mention if there are any limits on comments or transitions returned.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for each parameter (e.g., 'ATY-123' for issueKey, 'Criterios de aceptación' for extraFields), which helps the agent understand expected values beyond the schema 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?

The description uses a specific verb ('Devuelve') and clearly states the resource (issue) and the scope of what is returned (full context: description, parent, subtasks, linked issues, comments, transitions). It distinguishes from simpler sibling tools like jira_get_issue by emphasizing the comprehensive single-call nature.

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

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

The description explicitly states the intended use case: 'entender un ticket completo sin encadenar varias consultas' (understand a complete ticket without chaining queries). This implies when to use; it does not explicitly state when not to use or mention alternatives, but the context is clear.

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

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

No annotations provided, so description carries full burden. It discloses what fields are returned, but lacks details on read-only nature, authentication requirements, or potential side effects. Adequate but not comprehensive.

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 efficient sentences with no waste. First sentence states function and return content; second provides sibling guidance. Well-structured.

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 retrieval tool with good parameter descriptions, the description covers the essential purpose, returned data, and usage context. Slight gaps in error handling or full behavior, but largely 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 coverage is 100% and both parameters are described. The description adds value by explaining the 'fields' parameter's purpose with an example, going beyond the schema.

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

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

The description clearly states the tool retrieves a Jira issue by key, enumerating the fields returned (title, type, status, etc.), and distinguishes from jira_explain_issue for subtasks, links, and comments.

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

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

Explicitly tells when to use this tool (single issue retrieval) and when to use the sibling jira_explain_issue for subtasks, links, and comments, providing clear context for 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?

No annotations are provided, so the description carries full burden. It discloses the return fields (estimate, total, each worklog with details) and notes the ID is needed for deletion. However, it does not mention permissions, rate limits, or if the operation is read-only (likely safe).

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 concise with two well-structured sentences, front-loading the main purpose. A minor improvement could be clarifying the return of total spent vs. original estimate more succinctly.

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 no output schema, the description adequately explains return values (original estimate, total spent, each worklog with author, duration, date, description). It is complete for a single-parameter read tool with low complexity.

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

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

Schema coverage is 100% for the single parameter 'issueKey', and the description adds an example ('ATY-123') but no additional meaning beyond the schema's description. Baseline of 3 is appropriate.

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

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

The description clearly states that it returns time registered on a Jira issue, including original estimate, total spent, and each worklog with author, duration, date, and description. It also distinguishes from siblings like jira_add_worklog and jira_delete by mentioning the worklog ID necessary for deletion.

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 does not explicitly state when to use this tool versus alternatives. It implies a use case (getting worklogs for review or deletion) but provides no when-not-to-use guidance or comparison with other 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?

No annotations are provided, so the description must disclose behavior. It explains the output (issue types and field details) but does not explicitly state that the operation is read-only or mention any prerequisites, side effects, or auth requirements. The verb 'devuelve' implies read-only, but more explicit transparency would improve the score.

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 two sentences long, front-loads the main action, and contains no filler. Every sentence is necessary and conveys essential information efficiently.

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

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

Given the simplicity of the tool (2 parameters, no output schema), the description fairly covers the return values (identifiers, names, required, data type, allowed values). It does not explicitly describe the format of the issue type list when issueType is omitted, but the schema fills that gap. Overall, it is sufficiently complete for its complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters clearly. The description adds no new parameter-level details beyond the schema, meeting the baseline of 3.

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 explicitly states it returns issue types and their fields for a Jira project, with details like identifier, name, required status, data type, and allowed values. This is a specific verb ('returns') and resource ('issue types and fields'), distinguishing it from sibling tools like jira_create_issue or jira_get_issue.

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 advises using this tool 'antes de crear un issue' (before creating an issue), providing clear context. It implies the tool is for introspection and planning, though it does not explicitly contrast with alternatives like jira_create_issue.

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

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

With no annotations provided, the description discloses that the tool resolves against instance link types and lists possible relations if invalid. It implies a mutable operation (linking). It could further mention permissions or success response, but the provided information is useful.

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

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

The description is two sentences, direct and efficient, with no superfluous information. It front-loads the action and provides essential details.

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 description covers the core action, relation direction, and error handling. For a simple linking tool with no output schema, this is mostly complete. It could mention that it creates a link (modifies issues) or the success response, but the current text is adequate.

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

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

Schema coverage is 100%, but the description adds value by providing example values for issue keys (ATY-123, ATY-456) and clarifying the direction and valid relation strings. This goes beyond the minimal 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?

The description clearly states the tool links two Jira issues, specifies the directionality from first to second, and lists example relations. This is a specific verb+resource, and it distinguishes from sibling tools that handle other operations like getting or updating issues.

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

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

The description provides clear context on how to use the tool, including example relations and behavior when a relation type doesn't exist. However, it does not explicitly state when not to use this tool or mention alternatives, though the sibling tools are diverse and linking is unique.

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

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

With no annotations, the description carries the full burden. It discloses that results are sorted by last update and include key, title, type, status, priority, and last update date. It does not explain authentication or access limitations, but is otherwise transparent.

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 two concise sentences. The first sentence states the core functionality, the second provides an example query. No unnecessary words.

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

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

Given the tool's simplicity and full schema coverage, the description is mostly complete. It explains what is returned but omits details like default limit value (though schema says 20) and pagination. Still adequate.

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

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

Schema coverage is 100%, so the description adds little beyond the schema. The schema already describes limit, project, and includeDone with examples. The description does not provide new parameter insights.

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 clearly states the tool returns pending issues for the authenticated user, sorted by update date. It answers a specific natural language question and distinguishes from sibling tools like jira_search and jira_get_issue.

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 explains when to use (to get pending Jira issues) but does not explicitly state when not to use or mention alternatives. However, the purpose is clear enough for an agent to infer.

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?

Without annotations, the description bears full transparency burden. It states the tool reads open issues and returns aggregated data, with no side effects mentioned. While it doesn't explicitly declare read-only, the content implies it. The description adds behavioral context beyond schema, such as stale definition and output scope.

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

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

The description is concise: two sentences, no fluff. The first sentence covers the main purpose and elements, the second clarifies output type. Every word adds value, and it's front-loaded with key information.

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

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

Given no output schema and simple parameters, the description covers the main functionality: what data is returned (counts by status, type, priority, unassigned, stale) and parameter details. It lacks error or edge-case info, but for a summary tool, the coverage is adequate.

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%, with both parameters clearly documented (project key example and staleDays default). The description adds little beyond the schema, only mentioning 'stale days' implicitly. Baseline 3 is appropriate as schema already provides sufficient parameter semantics.

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

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

The description clearly states the tool's purpose: to summarize a Jira project's status from open issues, including counts by status, type, priority, unassigned, and stale issues. The verb 'Resume' and resource 'project' are specific, and the tool is distinct from siblings like jira_get_issue or jira_search, which handle individual issues.

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 implies usage for obtaining aggregated project data without assessment, and clarifies it returns data, not evaluations. It does not explicitly contrast with sibling tools, but the context shows it's for overviews. The 'no assessment' note provides clear guidance on output nature.

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

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

With no annotations, the description carries full burden. It discloses pagination behavior (returns one page, no total count estimate). It does not mention authentication or rate limits, but for a read-only search tool, this is acceptable.

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, no waste. The main purpose is front-loaded, followed by a key behavioral limitation. Every sentence adds value.

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

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

For a simple search tool with two parameters and no output schema, the description fully covers what the tool does, how it behaves (pagination), and its limitation. No obvious missing context.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds a JQL example and explains the limit default (20), and clarifies pagination behavior, providing value beyond the schema.

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

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

The description clearly states the tool searches Jira issues using JQL, specifies common use cases (by project, status, assignment, sprint), and differentiates from siblings like jira_get_issue by explaining it returns a page of results.

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 implies when to use (searching via JQL) but does not explicitly state when not to use or name alternatives. Sibling tools handle specific operations like single issue retrieval or creation, providing implicit differentiation.

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?

La descripción revela que si el destino es inválido, la respuesta lista estados posibles, y que admite comentarios. Sin embargo, no detalla qué sucede en caso de éxito (por ejemplo, si devuelve el issue actualizado) ni menciona requisitos de autenticación o permisos. La ausencia de anotaciones aumenta la necesidad de transparencia, pero la descripción cubre parcialmente el comportamiento.

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?

La descripción consta de tres oraciones sin contenido superfluo. Cada oración aporta información relevante (función principal, modo de uso, comportamiento ante error, soporte de comentarios). Es concisa y está estructurada de forma lógica.

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?

Para una herramienta con 3 parámetros, sin esquema de salida y sin anotaciones, la descripción es adecuada pero incompleta. Explica bien el parámetro principal y el manejo de errores, pero no describe la respuesta en caso de éxito ni qué devuelve la herramienta. La falta de esquema de salida hace que el agente se quede sin información sobre la respuesta.

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?

El esquema cubre todos los parámetros (100% de cobertura), pero la descripción añade valor significativo: explica que 'to' puede ser nombre de estado, nombre de transición o id, y que se resuelve contra transiciones actuales. También aclara que si es inválido, se listan los estados posibles, lo que no está en el esquema.

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?

La descripción indica claramente que la herramienta cambia el estado de un issue de Jira, diferenciándola de otras herramientas como jira_get_issue o jira_create_issue. Se detalla cómo especificar el destino (nombre del estado, nombre de la transición o id), lo que elimina ambigüedad.

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?

Se explica cómo usar la herramienta (indicar destino y opcionalmente comentario), pero no se menciona cuándo usar esta herramienta en lugar de alternativas (por ejemplo, jira_update_issue no parece cambiar estado). No hay guía explícita sobre cuándo no usarla ni comparación con herramientas similares.

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

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

With no annotations, the description carries full burden. It discloses partial update behavior, validation against editable fields, and custom field resolution. It does not contradict any annotation. Could add permissions or return value, but provides solid behavioral context.

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 concise sentences, each adding essential information: purpose, update mechanism, and validation constraint. No redundant or vague language.

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 9 parameters and no output schema, the description covers key aspects: partial update, validation, custom fields. Could mention response format or auth requirements, but current detail suffices for common use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining partial update semantics, editable field validation, and custom field usage with an example. This enriches parameter understanding.

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 clearly states 'Actualiza los campos de un issue de Jira', identifying the specific verb (update) and resource (issue fields). It distinguishes from siblings like jira_create_issue and jira_transition_issue by focusing on field updates.

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 explains partial update semantics ('Solo se envían los campos indicados; el resto queda intacto') and validation behavior ('Valida contra los campos que el issue admite editar'). It implicitly guides usage by contrasting with silent discard, but does not explicitly name alternatives for status transitions.

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

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

No annotations are provided, so the description bears full responsibility. It accurately indicates the tool is a read-only check (no mutations) and specifies what response it returns (version, build date). However, it could be slightly more explicit about its non-destructive nature.

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 exceptionally concise: two sentences that front-load the core purpose and provide a practical use case. There is 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 simple zero-parameter health-check tool, the description is fully self-contained. It explains both what the tool does and why an agent might need it, which is complete given the lack of output schema or complex parameters.

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 has zero parameters with 100% schema coverage. The description naturally implies no input is needed, which perfectly aligns with the schema. No additional parameter explanation is necessary.

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 clearly states the tool's specific purpose: checking server responsiveness and returning version and build date. It effectively distinguishes this tool from the listed sibling JIRA tools, none of which serve a health-check function.

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 explains when this tool is particularly useful—distinguishing between non-existent and undeployed capabilities—providing clear contextual guidance. While it does not explicitly state when not to use it, the scenario is well-defined.

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