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

With no annotations, the description does real work by declaring 'Read-only' and listing the required JIRA_BASE_URL, JIRA_EMAIL and JIRA_API_TOKEN environment variables. However it says nothing about result ordering, pagination, or the behavior when all four optional parameters are omitted, which an agent needs to invoke safely.

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, front-loaded with the purpose, then the query-construction rule, then the safety/auth note. No filler; the only minor compression cost is that 'combined with AND' is terse enough to be slightly ambiguous.

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 with zero required fields, no annotations and no output schema means the description should carry most of the burden. It covers query construction and auth prerequisites but leaves maxResults, defaults, and the zero-argument case unexplained, so an agent could still call it incorrectly.

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 compensate, and it does explain jql, projectKey and text and their AND combination. It omits maxResults entirely (no mention of paging or the 1-100 range) and does not clarify mutual exclusivity versus precedence between jql and the structured filters.

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 ('Search Jira issues'), which is immediately distinguishable from the tempo_* worklog siblings. It does not explicitly name an alternative or exclusion, but the domain difference is obvious from the name and title.

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?

'Provide either a jql string, or projectKey and/or text (combined with AND)' gives a concrete rule for how to drive the tool and implies the two query modes are alternatives. It stops short of stating precedence when both jql and projectKey are supplied, or what happens when no argument is given.

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 burden, and it discloses key traits: read-only, heuristic-only (cannot guarantee uniqueness), and the confidence/reason output shape. This is solid disclosure, though it doesn't explain what signal drives confidence levels.

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, each earning its place: purpose, return shape, and limitation. Front-loaded and zero 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?

With no output schema, the description steps up by describing return values (matches with confidence and reasons) and the heuristic limitation. It falls short only on explaining parameter roles for a 4-param 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 0%, so the description must compensate, but it only vaguely references 'the same issue and date' and 'proposed worklog.' It never explains description or durationMinutes or how these affect matching, leaving half the parameters 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?

Specific verb and resource: 'Compare a proposed worklog against existing Tempo worklogs for the same issue and date.' An agent can distinguish it from creation tools, though it doesn't explicitly contrast with tempo_validate_worklog or tempo_preview_worklog.

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 (check before creating to avoid duplicates), but there is no explicit when-to-use guidance or named alternative among the many worklog siblings. The heuristic caveat hints at when it's appropriate without stating it.

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 and does well: it discloses the write gating (env flag + confirm + token), post-write verification, and non-retry behavior on uncertain outcomes. It stops short of describing the response shape, error semantics, or permission scopes beyond the feature 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?

Four tight sentences: purpose first, then hard prerequisites, then failure behavior. No restatement of the title and no filler; the gating conditions are front-loaded where an agent will read them.

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 no annotations and no output schema, the definition covers the safety model and failure handling that matter most. The remaining gap is parameter meaning for five required/optional fields, which nothing else in the definition supplies.

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 compensate for all 7 parameters. It adds real meaning for two of them (confirm must be true; approvalToken must come from tempo_preview_worklog for the identical proposal), but issueKey, date, durationMinutes, description, and startTime are left entirely to the JSON Schema patterns and bounds.

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 ('Create a Tempo worklog') and immediately differentiates itself from write-adjacent siblings by requiring an approvalToken from tempo_preview_worklog. An agent can distinguish this from tempo_update_worklog or tempo_preview_worklog 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?

Explicitly names the preconditions for use: user approval, WORKLOG_WRITE_ENABLED=true, confirm=true, and an approvalToken for the exact same proposal. It also states the tool refuses to run without all three, which is a clear when-not-to-call signal, and routes the agent to tempo_preview_worklog as the prerequisite step.

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 and does meaningful work: it declares read-only behavior, states the TEMPO_API_TOKEN requirement, and discloses the key semantic that only actually recorded worklogs are counted. It does not describe the returned structure or volume, which keeps it below a 5.

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

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

Four dense sentences with the operation front-loaded, then week resolution, then the counting caveat, then the auth note. Every sentence adds information; no filler or repetition.

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

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

For an aggregation tool with no output schema and no annotations, the description covers the important semantics: scope, week resolution, default behavior, and the recorded-only counting rule. The main remaining gap is what the aggregate result actually looks like (day/issue grouping shape), plus the unresolved parameter precedence.

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 compensate. It gives useful meaning for `date`/`weekStartDate` (week resolution and default), but leaves the precedence between the two parameters ambiguous and never mentions `authorAccountId` (presumably defaulting to the caller), leaving one of three parameters 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 (aggregate), a specific resource (recorded Tempo worklogs), and the output granularity (by day and by issue) for a bounded scope (Monday..Sunday). This implicitly separates it from the raw-listing siblings like tempo_get_worklogs, 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?

Explains how the target week is selected (from `date` or `weekStartDate`, defaulting to the current week in the configured timezone) and clarifies that unrecorded days are reported as 'no recorded worklogs' rather than as missing work. No explicit when-not-to-use or named alternative is given, so it stops short of a 5.

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

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

No annotations are provided, so the description must carry the load: it does disclose read-only semantics and the TEMPO_API_TOKEN requirement, which is genuinely useful. It omits what happens when the ID does not exist (error vs empty), and gives no sense of the returned payload for a 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?

Two tight, front-loaded sentences with no filler; the read-only and auth facts arrive early. Minor noise comes from the 'tempoWorklogId' label that doesn't match the schema's parameter name.

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 one-parameter lookup this covers the essentials (what it fetches, that it is safe, that auth is needed), but with no annotations and no output schema it should also say what a worklog result contains and how a missing ID is surfaced.

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 single parameter has 0% schema description coverage, yet the description only restates its role ('by its tempoWorklogId') and even names it differently from the schema's 'worklogId'. No format, range (positive integer), or lookup-source guidance is added.

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

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

States a specific verb+resource ('Retrieve a single Tempo worklog') and scopes it to one record, which implicitly separates it from the sibling tempo_get_worklogs that lists many. It never names that sibling, so the differentiation is inferable rather than 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?

There is no guidance on when to pick this over tempo_get_worklogs, tempo_preview_worklog, or tempo_validate_worklog. The word 'single' hints at the by-ID lookup case, but usage is left to inference.

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

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

With no annotations, the description carries the full burden and does add real context: read-only semantics, an auth requirement (TEMPO_API_TOKEN), and inclusive range boundaries. It omits pagination/result-cap behavior despite a maxResults parameter capped at 5000, and says nothing about the shape or size of what comes back.

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 tight sentences with no filler; the date-range constraint leads, the optional filter follows, and the safety/auth facts close. Nothing repeats the schema verbatim.

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-parameter read tool with no annotations and no output schema, an agent still lacks pagination guidance and any hint about the returned worklog fields. The auth and inclusivity notes are valuable, but coverage is partial.

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. It explains the YYYY-MM-DD format and the crucial 'inclusive' boundary semantics for startDate/endDate and clarifies that authorAccountId scopes to one Jira user, but maxResults is never mentioned, leaving the pagination knob undocumented in both places.

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 (Retrieve) and resource (Tempo worklogs) plus the scoping dimension (date range, optional accountId), which cleanly separates it from the singular tempo_get_worklog and the aggregate tempo_get_week_summary. It doesn't explicitly name those siblings, so differentiation is inferred from the plural resource.

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 through 'date range' and 'optionally scope to one Jira accountId', giving enough for an agent to infer the list-vs-single distinction. But it never states when to prefer tempo_get_worklog, tempo_get_week_summary, or tempo_preview_worklog, leaving routing to the reader.

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 burden and does it well: it declares the tool is non-mutating, enumerates what the response contains (validation results, duplicates, approvalToken), and states that the token is required by the write tools. It omits operational details such as whether approval tokens expire or whether previews are persisted.

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 non-writing constraint and user-review workflow are front-loaded, followed by the two operation shapes and the return contract. Four dense sentences, none of which is filler or restates the title.

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

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

For a tool with no annotations and no output schema, the description supplies the missing behavioral contract: it is a read-only preview, what it returns, and how the returned token gates subsequent writes. The critical agent failure mode — skipping the preview and writing directly — is explicitly guarded against.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning beyond the schema: it names which fields belong to the create proposal versus the update changes object, and explains the approvalToken's role in the downstream workflow. The optional-field markers (startTime?, description?, etc.) mirror the schema rather than adding new constraints.

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 ('Prepare a proposed worklog for user review WITHOUT writing to Tempo'), and the emphasis on 'WITHOUT writing' distinguishes it cleanly from tempo_create_worklog and tempo_update_worklog. An agent can tell what this does and what it does not do 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 clear sequencing guidance: preview first, show the full result to the user, wait for explicit approval, then call a write tool. It also branches usage by operation=create vs operation=update. It stops short of explicitly positioning itself against tempo_validate_worklog and tempo_check_duplicate, which overlap in returning validation/duplicate results.

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 safety burden well: writes must be enabled, confirm must be true, and the token must match the exact worklogId and change set, which implies the update is rejected on mismatch. It does not disclose whether 'changes' is a partial patch or a full replacement, nor any token expiry or error-response 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?

Three short sentences, front-loaded with the action, then prerequisites, then scope boundary. No filler and nothing repeated from the schema.

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

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

For a mutation tool with no annotations, no output schema, and a nested changes object, the description covers gating and approval requirements thoroughly. The remaining gap is semantic: whether the changes object merges with or overwrites existing field values, which materially affects how an agent should populate 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 description coverage is 0%, so the description must compensate; it does so for the two non-obvious parameters, pinning confirm=true and defining approvalToken's provenance and matching constraint. worklogId and the nested changes fields are left to self-explanatory names and JSON constraints (patterns, min/max) rather than prose.

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 ('Update') and resource ('an existing Tempo worklog'), with 'existing' implicitly separating it from tempo_create_worklog. The closing note that no deletion exists in this MVP further fences the tool's scope against ambiguous destructive expectations.

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 precondition (explicit user approval) and the mandatory workflow: obtain an approvalToken from tempo_preview_worklog with operation="update" for the exact same worklogId and changes. It routes the agent to the correct sibling and states what must happen before invocation.

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 and does well: it names the tool as non-mutating and non-approving and discloses that the output is errors plus warnings. It does not mention permission requirements for access checks or any call cost/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?

Two tight sentences with zero waste; the positive scope comes first and the negative boundary clause is front-loaded at the end where it reads as a guardrail.

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 states that validation errors and warnings are returned, which is the key return-value fact. It stops short of explaining whether validation is all-or-nothing or per-field, a minor gap for a read-only validator.

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 5 parameters, so the description must compensate. It names the concepts being checked (issue key, date, duration, description, plus timezone/start-time warnings), giving partial mapping, but adds no format or constraint detail such as minute units, the 1-1440 range, or that startTime is optional.

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 (validate) and resource (proposed worklog), then enumerates the exact checks performed: issue existence/access, date, duration, description, timezone. The closing sentence explicitly separates it from write/approve siblings such as tempo_create_worklog, so an agent can distinguish it 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?

The negation ('Does NOT write and does NOT approve anything') implies this is a pre-flight check before creating a worklog, but the description never says so explicitly, nor does it route the agent between this tool and the close sibling tempo_preview_worklog. Usage is inferable rather than stated.

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