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

Annotations already declare idempotentHint=false, but the description adds the operative consequence — retrying can create a duplicate note — plus the immutable nature of existing journal entries. That is genuinely useful mutation context beyond the structured hints, though permission/auth behavior for this open-world write is not addressed.

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, with the core action and its non-idempotency caveat front-loaded. Every clause earns its place.

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

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

Return values need not be explained since an output schema exists, and the key risk (duplicate notes on retry) is disclosed. Minor gaps remain around auth/permissions given openWorldHint=true and the lack of any issueId format guidance for a write 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 must carry parameter meaning. It does implicitly map 'journal note' to notes and 'one existing issue' to issueId, but never states the identifier is an integer issueId or what content format notes accepts, leaving the mapping inferential for a mutating call.

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 ('Append a new journal note'), the exact resource scope ('one existing Redmine issue'), and carves out what it does not do ('without changing its fields'), which separates it from updateIssue and getIssueJournal in the sibling list.

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 context ('one existing issue', 'without changing its fields'), implicitly routing field edits to updateIssue, and warns against retrying. It stops short of naming an alternative tool or stating prerequisites explicitly, so it is clear but not fully prescriptive.

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=false and destructiveHint=false, but the description adds the concrete consequence an agent actually needs: retrying may create duplicate attachments. It also discloses that the file must be server-local and readable, which is a real operational constraint. Auth/permission requirements are not covered, keeping it out of 5 territory.

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

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

Two sentences, front-loaded with the action and scope, then the non-idempotency caveat and sibling pointer. No filler; every clause earns its place.

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

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

For a 3-parameter mutation tool with an output schema and full annotation coverage, the description supplies purpose, idempotency behavior, and sibling routing. The remaining gap is parameter-level detail and any permission/error expectations, which is minor given the output schema handles results.

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. 'server-local file' usefully clarifies that localPath is a path on the server rather than the client, and 'one existing issue' implies issueId must reference a valid issue. However, the optional description parameter and the format/type of issueId are entirely 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 (Upload/attach), a specific resource (one existing Redmine issue), and a constraint on the input (readable server-local file). It also distinguishes itself from getAttachment by naming that sibling's opposite flow, so an agent can separate the two 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?

Gives clear operating context: non-idempotent, retries may create duplicates, and getAttachment handles the reverse read/download path. It stops short of explicit when-not-to-use guidance (e.g., no size/permission prerequisites), so it is clear context rather than full routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds behavioral value by explaining the returned comparison categories (unique issues, shared issues, closure percentages). 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?

Two sentences with no filler; the primary purpose is front-loaded and the prerequisite for IDs is tacked on at the end. Every sentence earns its place.

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

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

For a read-only three-parameter comparison tool, the description covers what it does, what it returns, and how to obtain valid IDs. The output schema exists, so detailed return structure is not the description's responsibility.

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 each parameter already has a description including the listVersions source for versionIds. The description reinforces the version/milestone semantics but does not materially add new parameter meaning.

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

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

Description uses a specific verb 'Compare' with a defined resource ('issue scope and completion' of two versions/milestones) and names the outputs. This clearly distinguishes it from siblings like listVersions and getVersionChangelog.

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 states the context: comparing two known versions/milestones within one project, and tells the agent to use listVersions to discover IDs. It does not explicitly enumerate when-not-to-use alternatives, but the two-version comparison scope 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=false and idempotentHint=false, so the write/repeat semantics are covered; the description adds the genuinely new detail that the write is performed as the API-key user. The 'not idempotent' clause largely restates the annotation, so it stops short of 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 sentences, zero filler, with the create scope front-loaded and the routing constraint immediately after. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and annotations cover safety. The description covers mutation semantics, actor, idempotency, and the alternative tool; it does not mention the required projectId/subject pairing, but the schema marks those as required.

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 16 parameters and only 63% schema description coverage, the schema carries most of the burden. The phrase 'core or custom fields' loosely gestures at customFieldsJson and the field families, but adds no syntax, format, or mapping detail beyond what the schema already states.

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 (Create) and resource (Redmine issue) and scopes it to a known project with core or custom fields. The second sentence names the sibling it is not (updateIssue), so an agent can route without opening either schema.

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

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

Explicitly gives the when-not condition and the alternative: 'use updateIssue when the issue already exists'. Nothing about selection 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?

Annotations already declare idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description still adds value beyond the annotations by explaining the consequence — 'retries can duplicate time' — which an agent needs in order to decide whether to retry, and it scopes the record to the API-key user.

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 purpose and the issue/project constraint lead, and the non-idempotency warning plus activity routing follow immediately.

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, and the description covers the two highest-risk ambiguities: entry ownership/scoping and retry behavior. It stops short of describing hours constraints or customFieldsJson requirements, which remain thin at 43% coverage.

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?

At 43% schema coverage the description has to compensate, and it does on the most ambiguous point: issueId and projectId are mutually exclusive ('exactly one issue or project'), a constraint absent from the schema. The activityId routing hint is partly redundant with the schema, and hours/customFieldsJson semantics are left to 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 states a specific verb ('Record logged hours') and resource ('time entry') and pins down the scoping rule: 'against exactly one issue or project.' This is enough to separate it from the sibling list tools like listTimeEntries and getMyTimeEntries 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?

It routes the agent explicitly: 'use listTimeEntryActivities when an activity ID is needed,' which is directly actionable. It gives no explicit when-not-to-use guidance (e.g., bulk vs single entry), so it falls short of 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 readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds genuinely new behavioral context beyond them: it writes as the API-key user (auth/identity) and fails on duplicate title (concrete failure mode). It does not cover comment handling on an initial create, a minor omission against an otherwise informative write path.

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 creation behavior comes first and the routing rule second, which is the right order for a front-loaded tool description.

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 no explanation, and the annotations carry the safety profile. The description covers creation semantics, identity, duplicate-title failure, and the alternative tool. Only the undocumented comments parameter leaves a small 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 coverage is only 40%, with projectId and parentTitle documented in-schema; text, pageTitle, and comments are not. The description compensates for text ('complete initial text') and parentTitle ('optional parent'), but says nothing about pageTitle or comments, so the compensation is partial.

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 new Redmine wiki page') and narrows scope with 'complete initial text and optional parent'. It names the sibling updateWikiPage as the contrasting tool, so an agent can tell creation from update without opening a 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-not and alternative: 'fails if the title already exists; use updateWikiPage for an existing page.' This directly tells the agent which tool to pick for a pre-existing page, leaving nothing 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?

Goes well beyond the annotations by disclosing what actually happens: the file is downloaded to a server-local snapshot, text is extracted only for supported documents/archives, and images or unsupported binaries yield metadata plus a local path with no text. The note that truncated text remains readable at each part's localPath clarifies truncation behavior that no structured field captures.

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, front-loaded with the purpose, then ID-discovery guidance, then edge-case behavior — all content earns its place. Slightly dense with subordinate clauses, but there is 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?

For a read-only retrieval tool with an output schema carrying return shape and annotations carrying the safety profile, the remaining burden is behavioral and procedural context, and the description covers both — extraction scope, unsupported-binary handling, truncation, and the ID discovery path.

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 and attachmentId are undescribed), so the description must compensate, and it does in part: the 'limits' sentence ties maxChars/partLimit to truncation and 'each part's localPath' to the per-part model, and it says where attachmentId comes from via getIssue. issueId remains unaddressed in prose, keeping this just under a full 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 and resource ('Retrieve and inspect one known issue attachment') and adds the two mechanisms that define its behavior: local snapshot download and text extraction from supported documents or archives. This is readily distinguishable from attachFileToIssue and from getIssue, so an agent can route correctly.

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 precondition for use — the agent must already have an attachment ID and should obtain it via getIssue — which is genuine routing guidance. It does not name an explicit when-not or an alternative tool for listing attachments, 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?

The annotations already establish readOnlyHint, non-destructive, and idempotent behavior. The description adds meaningful behavioral detail beyond those annotations: traversal is recursive in both directions and returns full dependency chains. This is useful context not inferable from the annotations or schema, though it does not cover edge cases like cycles or depth 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?

Two sentences with no filler: the first sentence states the core behavior and scope, and the second sentence provides a direct pointer to the relevant sibling tool. The most important 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 read-only, single-parameter tracing tool with an output schema, the description covers the essential behavior and sibling differentiation. It does not mention potential cycle handling or whether the full chain includes the starting issue itself, but these are minor given the annotations and schema 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?

The schema has only one parameter, issueId, and no description in the schema (0% coverage). The description does not explicitly document the parameter, but the tool name and the context of tracing relations make it reasonably clear that issueId identifies the starting issue. This is adequate for a single self-explanatory parameter, but the description misses the chance to explicitly say 'starting from the given issue.'

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

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

The description names a specific verb ('Trace') and a specific resource ('blocks/blocked_by relations'), and further defines the scope as recursive in both directions, returning full upstream and downstream chains. This clearly distinguishes it from the sibling getIssueTree, which handles parent/subtask hierarchy and other relation 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 explicitly tells the agent when to use this tool versus an alternative: 'Use getIssueTree for parent/subtask hierarchy and other direct relation types.' It also scopes its own applicability to exactly blocks/blocked_by relations, leaving no ambiguity about when to select 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about how the returned ID is used, which goes beyond the annotations without contradicting them. A minor gap is no mention of error behavior, but this is trivial for a read-only identity fetch.

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 with zero filler. It front-loads the core purpose and immediately provides actionable usage guidance. Every word earns its place.

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

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

With no parameters and an output schema provided, the description covers everything an agent needs: what the tool returns, how to use it, and which scenarios don't require it. There are no missing prerequisites or edge cases that would leave an agent confused.

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, so the baseline is 4. The description correctly notes there are no required inputs and does not need to explain any parameters. It adds value by explaining the purpose of the output, which is more than sufficient.

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 the identity and user ID of the authenticated API-key user. The verb 'retrieve' is specific, the resource is well-defined, and the mention of using the ID in filters distinguishes it from sibling tools that don't require 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?

The description explicitly tells when to use the tool: to get the user ID for assignee/user filters. It also names specific sibling tools (getMyIssues, getMyTimeEntries, default getUserWorkload) that do not require this ID, providing clear exclusions and alternatives.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile and idempotency. The description adds detail about focus modes affecting compression, which is useful behavioral context. It doesn't mention pagination, rate limits, or exact return format, but with output schema present, that's less critical. So a 3 is appropriate.

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 core purpose and then immediately offering alternatives, which is efficient. It packs a lot of information without fluff, every clause 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 read-only tool with an output schema, the description covers the tool's purpose, its scope, the existence of focus modes for compression, and clear routing to siblings. Given the complexity (returns many data types) and the output schema providing return structure, the description is complete enough. It lacks some details like default focus behavior, but that is minor given the other resources.

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 50%: issueId has only a type/format, no description; focus has a brief description of allowed values. The description explains the purpose of focus modes and names them, adding context not in the schema, such as what each mode compresses (e.g., implementation, timeline, changesets, full). However, it doesn't dive into full parameter semantics for issueId beyond implying it's the known issue ID. With partial coverage, the description adds value but not comprehensive.

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?

Clearly states it retrieves complete context for a single known issue ID, enumerating the included data types (core/custom fields, subtasks, relations, journals, attachments, changesets). It also names three sibling tools (getIssueTree, getIssueJournal, getAttachment) and specifies what each provides, effectively distinguishing from 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 directs when to use alternatives: recursive structure via getIssueTree, journal retrieval if omitted or shortened via getIssueJournal, and file content via getAttachment. Also mentions focus modes that control compression, implying when to use them, though not exhaustive. Overall, strong guidance on 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds meaningful behavior beyond them: long text is truncated and remaining events require pagination via nextOffset, which tells the agent the result may be incomplete.

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 dense sentences with zero waste: the core action is front-loaded, then truncation and the paging/alternative escape hatch follow. Nothing is redundant with structured fields.

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 shape needn't be explained, and the description still covers the two things an agent must know to use the result correctly (truncation and pagination). Complete for this tool's 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 only 50% – offset is documented in the schema, issueId is not. The description refers to nextOffset for pagination but adds no format or meaning for issueId, so it only partially compensates for the coverage 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?

The description states a specific verb and resource ('Read an issue's chronological journal events and status intervals') and explicitly distinguishes itself from the sibling getIssueJournal. An agent can separate this from getIssue 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 routes the agent to getIssueJournal when full text is needed, and names nextOffset as the way to page through remaining events. That covers the main alternative and continuation path, though it doesn't say when not to use history at all.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral fact beyond annotations — no response compression, i.e. full text returned — but says nothing about auth, pagination, or size 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?

A single sentence with zero waste; the retrieval scope is front-loaded and the ID-source caveat follows immediately, so an agent can parse it in one pass.

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-value explanation is not required, and annotations carry the safety profile. The only remaining gap is the undocumented issueId parameter, which is minor for this simple two-parameter read 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 only 50%: journalId is documented in the schema and reinforced by the description's provenance note, but issueId has no description anywhere. The description compensates for the journalId side but leaves issueId's semantics (which issue, format) 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 and resource ('Retrieve one known issue journal entry in full') plus the distinguishing scope ('without response compression'), which clearly separates it from getIssue and getIssueHistory that return aggregated or compressed content.

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 the agent where to get the journalId ('from getIssue or getIssueHistory') and the condition for using this tool ('when exact text is needed'). It doesn't state when not to use it, but the trigger condition is clear enough to route correctly.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds a genuine behavioral trait beyond them: root and ancestor nodes come back compact rather than full, which tells the agent when a follow-up getIssue call is needed.

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 filler. The traversal scope is front-loaded and the sibling routing follows immediately, so nothing is buried.

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, and the description covers traversal direction and the compact-node caveat. The one gap is depth's default/limit behavior (e.g. what happens if depth is omitted or very large), which affects how the agent calls it but is 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 50% – depth is documented in the schema, issueId is not. The description restates depth in natural language ('down to the requested depth') but adds no format, default, or bounds information beyond the schema, so it neither compensates for the gap nor regresses from the baseline.

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 ('explore one issue's parent chain and subtasks') with the traversal scope ('down to the requested depth'). It explicitly distinguishes itself from siblings getIssue and getBlockerChain, so an agent can route without opening a 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 two concrete alternatives and the condition that selects each: getIssue for full details or relations, getBlockerChain for blockers. The tree-shaped subset this tool returns is framed as the reason to pick it over those, 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 description adds meaningful behavioral context beyond the annotations by clarifying that the tool operates against the currently authenticated API-key user and does not require a prior user-ID lookup. Given readOnlyHint and idempotentHint already cover the safety model, this is a strong addition, though it does not detail response pagination or filtering edge cases.

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-load the core purpose and immediately route to relevant alternatives. There is no filler, repetition, or gratuitous 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?

With an output schema present, no return-value description is needed. The 5 optional params are mostly described in the schema, and annotations cover safety and idempotency. The only slight gap is the lack of guidance on limit/offset usage, but overall the description is complete enough for correct 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?

The schema already has useful descriptions for sort, statusId, and projectId, so the description adds no extra parameter-level detail. Because limit and offset are still undocumented and the description does not compensate for that gap, a mid-range score 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 states a specific action ('Browse issues'), a specific scope (assigned to the currently authenticated API-key user), and the key benefit (no need to first resolve the user ID). It also distinguishes itself from sibling tools like listIssues and getUserWorkload in one sentence.

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 explicitly routes to alternatives: getUserWorkload for aggregated workload metrics and listIssues for another assignee. This gives the agent clear decision heuristics about which sibling to pick based on the user's goal.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral context that this tool avoids the need to resolve the user ID first, which is useful. However, it doesn't disclose anything about pagination, filtering behavior, or what happens when no time entries exist. With annotations covering the safety profile, a 3 is appropriate.

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 zero waste. The core purpose and the key differentiator are front-loaded, and the alternative is named in the second sentence. Every word earns its place.

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

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

The tool has an output schema, so return values are covered. The description explains the key behavioral nuance (no user ID resolution needed) and routes to the alternative. The only minor gap is that the description doesn't mention that all parameters are optional or that the tool returns only the current user's entries, but the purpose statement already implies the scope. This is complete enough for a read-only list tool with an output schema.

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

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

Schema description coverage is 50%, so the schema documents 'to', 'from', and 'projectId' but leaves 'limit', 'offset', and 'issueId' without descriptions. The description doesn't add parameter-level meaning beyond what the schema provides. Baseline 3 is correct when the schema does partial heavy lifting and the description doesn't compensate for the undocumented parameters.

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 ('Browse'), a specific resource ('actual time-entry records logged by the currently authenticated API-key user'), and a key differentiator ('without first resolving their user ID'). It clearly distinguishes itself from listTimeEntries, which is for another user or broader administrative filtering.

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 says when to use this tool: to browse the current user's time entries without resolving the user ID. It also names the alternative (listTimeEntries) and the condition for using it ('for another user or broader administrative filtering'). This is explicit when/when-not 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety and side-effect profile. The description adds minimal behavioral detail beyond the annotations; it says 'Inspect' which aligns with read-only, but it doesn't disclose additional behavioral traits like authentication requirements or performance characteristics. Since the annotations are comprehensive, the description adds only marginal behavioral value.

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 with zero wasted words. The first sentence front-loads the primary purpose and content, and the second sentence provides targeted alternatives. This is a model of concise, structured tool documentation.

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 single parameter, the presence of an output schema, and comprehensive annotations, the description is complete for an agent to select and invoke the tool correctly. It states what the tool returns (configuration and metadata including description, trackers, enabled modules) and when to use alternatives, leaving no critical gaps.

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

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

The input schema fully documents the single parameter, projectId, with 'Project identifier or numeric ID' (100% schema coverage). The description does not add any further meaning or constraints about the parameter beyond what the schema already provides. With full schema coverage, the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Inspect one known project's configuration and metadata' with a specific verb ('Inspect') and resource ('project configuration and metadata'). It also lists what is included (description, trackers, enabled modules) and distinguishes from siblings by naming alternatives. This makes it immediately clear what the tool does and how it differs from related tools.

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 provides when-not-to-use guidance: 'Use getProjectSummary for aggregated issue metrics, listProjectMembers for people or listVersions for milestones.' This directly tells an agent which alternative to choose based on the need, leaving no ambiguity about when this tool is appropriate.

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 cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is known. The description adds behavioral context beyond that: the summary spans only the open-issue set and includes specifics like estimated-vs-spent hours and distributions. It does not mention auth or rate limits, but those are not essential given the annotation coverage. 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?

The description is a single dense sentence with a clear purpose and a final usage pointer. Every clause adds measurable detail (totals, distributions, overdue, hours). It is moderately long, but the information is front-loaded and no filler exists.

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 read-only aggregation tool with two parameters, an output schema, and full annotation coverage, the description leaves nothing essential uncovered. It clearly explains what the tool returns (aggregates), how scope is controlled (milestone), and when to choose listIssues instead. An agent can invoke this tool correctly based solely on the given description plus schema.

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

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

Schema description coverage is 100%, and both parameters are already described ('Project identifier or numeric ID', 'Version/milestone ID; from listVersions'). The description's 'optionally scoped to a milestone' only echoes the existing optional parameter. The schema carries the semantic load, so the 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 opens with a specific verb ('Summarize') and a concrete resource ('one project's issue health'), then enumerates distinct facets (totals, status/tracker/priority/assignee distributions, overdue, hours). It explicitly contrasts with the sibling listIssues, so an agent can tell them apart 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?

It gives explicit guidance: 'Use listIssues when issue records are needed instead of aggregates.' This names an alternative and gives the exact condition that triggers the switch. It also states the optional scope of 'to a milestone', telling the agent when versionId is useful.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the tool's behavior, namely that it returns a risk score and aggregates issues, which is useful beyond the annotations. However, it does not disclose details like how the risk score is computed, pagination, or the exact structure of the output. Given the annotations, a 3 is appropriate; the description adds moderate context but not deep behavioral detail.

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 front-loads the core purpose and then lists the types of issues checked. It ends with the alternative routing. Every word is purposeful with no padding; it is efficient and well-structured for agent consumption.

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 is a read-only risk assessment, and the annotations plus schema cover the safety profile and parameters. The description explains what it does and when to use it. Since an output schema exists, return value details aren't required. The main missing piece is the risk score's calculation semantics, but that doesn't block correct invocation. Given the clarity and routing, it is nearly complete, so a 4 is appropriate.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the note that versionId comes from listVersions. The description does not add new meaning to the parameters (e.g., no format hints for projectId or versionId beyond schema), but that's acceptable because the schema carries the burden. Baseline 3 is correct.

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 purpose: assessing readiness risks for a version/milestone, and enumerates concrete issue types it checks (blockers, overdue work, high-priority issues, unassigned tasks) plus a risk score. This clearly distinguishes it from siblings like getVersionChangelog, which is explicitly named as the alternative for issue breakdowns.

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 the agent when to use this tool (for risk assessment of a known version/milestone) and when not to (use getVersionChangelog for milestone issue breakdown rather than risk triage), naming the specific alternative tool. This is clear routing guidance that prevents mis-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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds behavioral context by specifying that it filters open issues, orders by staleness, and is for inactivity triage, which is beyond what annotations provide. It doesn't contradict annotations.

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

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

The description is two sentences, front-loaded with the core purpose and a pointer to the alternative. Every word earns its place.

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

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

With an output schema present and annotations covering safety, the description provides sufficient context for calling the tool: it clarifies the filter (open issues), the ordering, and the use case. It doesn't mention defaults or pagination, but that's minor given the output schema.

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

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

The schema already describes projectId and daysSinceUpdate, covering 67% of parameters. The description indirectly refers to daysSinceUpdate via 'last-update age' but doesn't add explicit parameter meaning. Since schema coverage is high, a 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 uses a specific verb 'Identify' and a clear resource 'neglected open issues in one project', and specifies ordering 'most stale first'. It also names the sibling tool 'listIssues' and clarifies the distinction, making the 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?

It explicitly instructs to use listIssues for general field or status filters and states this tool is for inactivity triage, providing a clear when-to-use and an alternative. This guides the agent to choose correctly.

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, idempotentHint, and non-destructive behavior, so the description does not need to cover safety. It adds meaningful behavioral context by clarifying that the result is an aggregate view rather than issue records, and that omitting userId changes the target user to the API-key user.

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 carry significant value with no filler. The core behavior and filters are front-loaded, followed by the aggregate-versus-records distinction and a concise pointer to alternatives.

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 that an output schema exists, the annotations already cover the safety profile, and the description covers user selection, aggregation semantics, and sibling routing, nothing essential is missing for an agent to invoke this 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 only 50% because userId lacks any schema description. The description compensates by explaining the optional userId semantics, including the API-key user fallback. projectId is already described in the schema as 'Project identifier or numeric ID', and the description reinforces its role in workload analysis.

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 ('Analyze one user's open-issue workload') and enumerates the analysis dimensions: project, priority, overdue count, estimated versus spent hours, and top issues. It also explicitly differentiates itself from siblings by noting it returns aggregates, not issue records, and names getMyIssues and listIssues as the alternatives.

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?

Provides clear routing guidance: use getMyIssues for the current user, listIssues for a specified user when issue records are needed, and this tool for aggregate workload analysis. Also explains the important behavior that omitting userId selects the API-key user, giving agents concrete selection criteria.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the tool summarizes rather than mutates and that it targets a single known version, which is useful behavioral context beyond 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?

Two sentences with no fluff. The primary purpose is front-loaded, and the alternative-tool guidance is compactly placed at the end. Every clause earns its place.

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

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

With an output schema present and robust annotations, the description only needed to clarify scope, output grouping, and how to obtain the version ID—all of which it does. An agent can correctly select and invoke this tool without additional 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 the baseline is 3. The description's 'listVersions to discover the version ID' largely repeats the schema hint for versionId, and projectId is already self-explanatory in the schema. No new parameter-level meaning 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?

The description states a specific verb and resource: it summarizes one known version/milestone. It also specifies the output form (open and closed counts, grouped by tracker), which clearly separates it from generic changelog or comparison tools. The naming of getReleaseRisks and listVersions further disambiguates its niche.

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 explicitly says to use getReleaseRisks when readiness risks are the goal, and listVersions when the version ID is unknown. This gives the agent an immediate routing decision against the most relevant siblings. No inference is required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond that: it returns complete markup and the current version, and requires a known page title. This is useful supplemental detail without contradicting the 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?

Two sentences, front-loaded with purpose, then usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

With an output schema present to document return values, and annotations covering safety, the description covers all critical usage aspects: how to discover the title, what the return includes, and the relationship to updateWikiPage. Nothing essential is missing for an agent 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 coverage is 100%, so the baseline is 3. The description adds the 'use Wiki for the start page' hint for pageTitle, which is helpful but also present in the schema. No significant extra parameter meaning is provided beyond the schema, so a 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 the verb (read), the resource (project wiki page), and the exact scope (complete markup content and current version). It distinguishes itself from sibling tools like listWikiPages and searchWikiPages by specifying 'one known project wiki page', implying the caller must already have the exact 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?

It explicitly instructs when to use this tool: after discovering the title via listWikiPages or searchWikiPages. It also states the returned version is required by updateWikiPage, giving a clear prerequisite and downstream use case. This provides both when-to-use and when-not-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?

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds value by disclosing that the output is meant to be reused as categoryId and that the lookup is scoped to one known project, which informs how the agent should use the result.

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-load the purpose and add one directly actionable usage note. There is no redundant restatement of the tool name, title, 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?

For a single-parameter read-only list tool with an output schema, the description fully supports correct invocation: the agent knows the required projectId, the nature of the returned data, and how to consume it downstream. Nothing essential 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 100%, so projectId is already described as 'Project identifier or numeric ID'. The description adds no additional parameter syntax or constraints beyond the idea of a known project, which is acceptable since the schema carries the parameter meaning.

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?

Clearly states a specific verb+resource: list issue categories for one project, and names the meaningful output (IDs and names). It distinguishes itself from sibling metadata tools like listPriorities, listStatuses, and listTrackers by focusing specifically on issue categories.

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?

States it is for discovering category IDs for a known project and explicitly connects the result to createIssue or updateIssue via categoryId. It does not name excluded alternatives, but the 'one known project' scope and category-specific purpose give an agent clear context to select it correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it returns 'issue summaries' (not full details) and mentions pagination, which is useful. However, it doesn't disclose default sort order, default limit, or how custom field filters interact with other filters. The description adds minimal context beyond the annotations, so a 3 is appropriate.

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 front-loads the core purpose and key capabilities, then adds a concise routing instruction. Every word earns its place; there is no fluff 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?

Given that the tool has an output schema, the description doesn't need to explain return values. It covers the core function (browsing issue summaries), key filters, sorting, pagination, and sibling differentiation. It could benefit from noting that it only returns summaries (not full details) and maybe a default limit, but these are minor given the output schema and annotations.

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 73%, so the schema already documents most parameters. The description adds context that queryId is from listQueries, statusId can be 'open' or 'closed' (default), and customFieldFilters are in query-string form, which goes beyond the schema for those fields. However, several parameters (assignedToUserId, limit, offset) lack descriptions in both the schema and the description, leaving some gaps. The description adds value but not enough to fully compensate for the uncovered parameters.

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 ('Browse') and resource ('issue summaries') and immediately enumerates the key dimensions (filters, saved queries, custom-field filters, sorting, pagination). It also differentiates itself from siblings by naming searchIssues (free text) and getIssue (complete context for one issue), so an agent can clearly tell this is the list/browse tool.

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 tells when to use this tool versus alternatives: use searchIssues when only free text is known, or getIssue for one known issue's complete context. This gives clear selection criteria, though it doesn't exhaustively list all sibling alternatives (e.g., getMyIssues), but the guidance provided is strong enough for this purpose.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the behavioral context that this is a discovery/lookup operation and that the returned IDs are meant to be reused. However, it doesn't describe the output format or whether the list is ordered, but with a rich output schema present and annotations covering safety, a 3 is appropriate.

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 wasted words. The first sentence states the purpose and the second provides the reuse guidance. It is front-loaded with the core action and immediately gives the agent the key information needed to use the tool correctly.

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 zero-parameter, read-only lookup tool with an output schema and strong annotations, the description is nearly complete. It explains why the tool exists and how to use its output. The only minor gap is that it doesn't mention whether the list is exhaustive or ordered, but the openWorldHint annotation and output schema likely cover the return structure. This is a minor gap, not a significant one.

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, so there is no parameter semantics burden on the description. The schema coverage is 100% (vacuously, since there are no properties). The description adds value by explaining the purpose of the output (valid IDs for reuse), which is more than the empty schema provides. Baseline 4 for zero-parameter tools 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 the tool's purpose: discovering valid issue priority IDs and names. It specifies the resource (issue priorities) and the action (discover/list), and it explicitly distinguishes its role as a lookup tool for use before filtering, creating, or updating issues. This differentiates it from sibling tools like listStatuses or listTrackers, which serve different lookup purposes.

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 when to use this tool: before filtering, creating, or updating issues. It also tells the agent how to reuse the output (as priorityId in listIssues, createIssue, or updateIssue). This is clear, actionable guidance that routes the agent to the correct tool and explains the downstream 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about membership vs. workload, but it does not disclose behavioral details such as default pagination behavior, open-world semantics, or any access 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 two concise sentences with no filler. The core purpose and output scope are front-loaded, followed by a focused usage note naming the alternative 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?

With annotations covering safety, an output schema present, and the required projectId clearly identified, an agent has enough to invoke the tool correctly. The only notable omission is a description of limit/offset, but this is minor for standard pagination parameters and does not block correct 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 description coverage is only 33%; only projectId has a schema description, while limit and offset are undocumented. The description reinforces that projectId identifies one project, but it does not explain limit/offset pagination semantics, leaving a real gap for those parameters.

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

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

The description names a specific verb and resource: it 'discovers' the users/groups of a project and reports their IDs and roles. It also explicitly distinguishes itself from getUserWorkload, which analyzes a user's issues rather than project membership, so an agent can tell them apart immediately.

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 the tool: 'Use when choosing or interpreting assignees.' It also names the closest alternative, getUserWorkload, and explains why that tool is not the right choice for membership questions. This gives clear 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context beyond these annotations by stating that only 'accessible' projects are listed, which implies authentication and permission filtering, and by clarifying that the return is project summaries rather than full details. No contradiction exists.

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 with no wasted words. It front-loads the primary purpose and action, then includes the key alternative. Every sentence earns its place, and the structure makes it easy for an agent to parse the core intent quickly.

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 that the tool has an output schema, the return value format is already covered. The description provides the purpose, usage timing, and the main alternative, while annotations cover safety and idempotency. The only gap is that limit and offset are not described in either the schema or the description, which is a minor omission for a simple listing tool with optional 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 schema has 0% description coverage for parameters, and the description does not mention limit or offset at all. The parameter names are somewhat self-explanatory as pagination controls, but the description adds no explicit meaning about their behavior, defaults, or relationship to result size. Given the low schema coverage, the description should have compensated but does not.

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 ('Discover accessible Redmine projects and their valid identifiers') and the specific resource (Redmine projects), giving agents a precise understanding of what the tool does. It also differentiates from the sibling tool getProject by noting that listProjects returns summaries while getProject provides one project's details.

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 tells the agent when to use this tool: 'before project-scoped operations when the target project is unknown.' It also names the alternative, getProject, and states the condition for choosing it ('for one project's details'). This is clear, actionable guidance that routes the agent correctly.

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/idempotentHint, so the description's added value is contextual: it reveals that results are query metadata (IDs/names) rather than issues, and that the output feeds listIssues. It does not mention pagination behavior for limit/offset, but the output schema and read-only annotations lower the burden.

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, each earning its place: the first defines the purpose/scope, the second clarifies the return type and the follow-up workflow. The key distinction from listIssues 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 read-only, zero-required-parameter listing tool with an output schema, the description covers purpose, scope, return shape, and downstream use. The only real gap is that limit/offset remain semantically undocumented in both schema and prose, which is minor because they are optional and self-explanatory as pagination terms.

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 the description provides no explanation of limit or offset. The parameter names weakly imply pagination controls, but the description neither confirms nor documents their meaning, defaults, or constraints, so it fails to compensate 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?

The description names a specific verb and resource ('Discover saved Redmine issue queries (stored filters)') and distinguishes it from sibling list tools by stating that it returns query IDs and names, not issue results. It also explicitly routes to listIssues for the follow-up call, making the tool's role 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?

It gives a clear when-to-use signal ('especially filters involving custom fields') and an explicit when-not/alternative: 'Returns query IDs and names rather than issue results; pass a selected queryId to listIssues.' An agent can decide between listQueries and listIssues without additional inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to restate those. It adds useful context about reusing IDs as statusId, but it does not describe other behavioral traits such as pagination, ordering, or response shape. No contradiction with annotations exists.

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 with no filler. The primary purpose is front-loaded in the first sentence, and the second sentence immediately explains practical downstream usage.

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 zero-parameter lookup tool with strong annotations and an output schema present, the description is fully sufficient. It explains what is returned, why it matters, and how the results should be used in sibling tools.

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, so the input schema provides no semantics to enhance. The description still adds value by clarifying that the tool returns IDs and names rather than requiring inputs. Baseline 4 is appropriate here.

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 identifies the tool's purpose: discovering Redmine issue status IDs and names. It also distinguishes itself from sibling list tools like listPriorities and listTrackers by explicitly limiting scope to issue statuses and positioning them as canonical inputs for statusId.

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 gives clear usage context: use this tool to discover valid status IDs for filtering or mutation, and reuse the IDs in listIssues, createIssue, or updateIssue. It does not explicitly state when not to use it or name exclusion conditions, 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?

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds useful behavioral context by emphasizing that it returns actual time-entry records rather than aggregates, and by specifying the available filter scopes. It does not cover pagination or default limits, but the annotations carry the safety profile.

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 filler. The core purpose is front-loaded, and the alternative routing is packed efficiently into the second 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?

The description gives the essential selection criteria and explicitly routes to relevant siblings. It does not mention that all parameters are optional or how pagination behaves, but the empty required list and output schema reduce the need for that detail. Overall it is sufficient for correct tool selection and basic invocation.

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 43%, so the description must compensate. It does add meaning for project, issue, user, and date-range parameters by naming them as filters, but it leaves limit and offset unexplained. The schema describes only to, from, and projectId, so those two pagination parameters remain underspecified.

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 a specific verb ('Browse') and resource ('actual Redmine time-entry records'), and names the filter dimensions. It also distinguishes itself from getMyTimeEntries and getUserWorkload, so an agent can tell them apart immediately.

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 explicitly says to use getMyTimeEntries when targeting the API-key user without an ID lookup, and getUserWorkload when aggregates are needed. This gives concrete when-to-use and when-not-to-use guidance relative to siblings.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds purpose and linkage to createTimeEntry but does not describe return format or pagination. It adds value but not rich behavioral detail beyond 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?

Two sentences, no fluff, and the core purpose is front-loaded. Every phrase earns its place, and the linkage to createTimeEntry is stated 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?

For a zero-parameter tool with an output schema, the description is complete. It explains what the tool returns (IDs and names), why it matters (interpreting hours, creating entries), and how to use the result. Nothing essential 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 has zero parameters, so the schema description coverage is trivially 100%. The baseline of 4 applies because no parameter documentation is needed; the description appropriately focuses on output purpose and usage.

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 clear verb ('Discover') and a specific resource ('valid time-entry activity IDs and names'), and explicitly ties it to createTimeEntry, differentiating it from the many other list tools. The purpose is unambiguous and provides actionable context.

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 gives an explicit when-to-use scenario: interpreting logged hours or creating a time entry, and even specifies a condition ('when the default activity is unsuitable'). It lacks an explicit when-not-to-use statement, but the context is strong enough for an agent to route correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds valuable context about the purpose (discovering reusable IDs) and clarifies terminology ('issue type'). Does not contradict annotations.

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

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

Two concise sentences, no fluff. The core purpose is front-loaded, and the reuse guidance is clear. Every sentence earns its place.

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

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

With an output schema available and annotations covering safety, the description fully explains why and when to use the tool and how the result is consumed. Nothing an agent needs to decide on or call the 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?

No parameters exist, so the baseline is 4. The description correctly notes that no inputs are needed and explains the output's purpose, though it doesn't detail output structure – but an output schema is present, so this is acceptable.

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 'Discover' with a clear resource 'valid tracker (issue type) IDs and names' and its purpose for reuse. Clearly distinguishes from sibling tools like listIssueCategories and listPriorities by specifying trackerId usage.

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 when to use it: 'before filtering, creating or updating issues' and names the exact tools (listIssues, createIssue, updateIssue) that consume the IDs. No ambiguity about when this tool is relevant.

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 cover read-only, idempotent, non-destructive, open-world hints. The description adds context about data scope (milestone metadata only, not issue scope/risk), which goes beyond annotations and informs the caller about expected results.

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 tightly packed sentences with zero fluff: the first establishes purpose and key output, the second clarifies exclusions and routes to alternatives. Front-loaded and efficient.

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 tool with a defined output schema and annotations covering safety and open-world semantics, the description fully covers purpose, exclusions, and alternatives. No missing critical 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?

Schema coverage is 100% (projectId has a description), so baseline is 3. The description mentions 'of one project' but adds no extra syntax or parameter behavior beyond the schema's own 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 description states a clear verb ('Discover') and resource ('versions/milestones of one project'), and explicitly notes what it returns (IDs for filters/analytics) and what it does not (scope or risk), distinguishing it from siblings by name.

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 names the alternatives (getVersionChangelog, getReleaseRisks) and the conditions for choosing them, giving explicit when-to-use and when-not-to-use guidance without ambiguity.

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 cover safety (readOnlyHint, idempotentHint, destructiveHint). The description adds a meaningful behavioral trait beyond annotations: it does not load every page body, implying it is a lightweight listing operation that returns only titles. This is useful context for an agent deciding between this and heavier alternatives.

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 concise sentences, each earning its place. The first front-loads the core purpose and key limitation (no page bodies), and the second gives actionable routing to alternatives. No redundancy or fluff.

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 listing tool with one parameter and an existing output schema, the description is complete. It covers what it returns (titles), the precondition (known project), and directs to alternatives when appropriate. Nothing essential 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 description coverage is 100% for the single parameter projectId, so the schema already fully documents it. The description adds no extra semantics about the parameter format or constraints, which is acceptable given full schema 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?

The description states a specific action ('Discover wiki page titles') on a specific resource ('one known project') and adds a key distinguishing detail ('without loading every page body'). It also names the sibling tools that are NOT this one, making the purpose unambiguous even among 30+ 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?

The description explicitly provides when-to-use and when-not-to-use guidance: it directs the agent to getWikiPage when a title is already known, and to searchWikiPages when only content terms are known. It also clarifies the precondition 'one known project', which implies projectId is required.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is well covered. The description adds the mixed-content breadth but does not disclose pagination defaults, result ordering, or whether all content types are searched by default. For a simple read-only search tool this is acceptable, though not richly 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?

Two sentences with no filler. The core action and scope are front-loaded, and the sibling recommendations occupy the second sentence without bloating the description.

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-value details are not the description's job. Annotations cover read-only/idempotent behavior. The description provides scope, content types, and sibling routing. It could mention default type behavior or pagination, but for a mixed-content search tool the definition is fairly 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 only 40%, so the description must compensate. It does add meaning for the required searchQuery as 'free text' and clarifies the content types in plain language, but it provides no additional guidance for limit, offset, or projectId beyond the schema. This is partial compensation rather than full.

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 ('Search by free text') and a concrete resource ('mixed Redmine content'), enumerates the content types, and explicitly names sibling tools it is not (searchIssues, searchWikiPages). An agent can immediately tell what this tool does and how it differs from nearby alternatives.

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 gives clear routing guidance: use searchIssues for richer issue-only results and searchWikiPages for wiki-only discovery. This explicitly tells an agent when to prefer alternatives over searchAll, which is exactly the kind of decision support this dimension rewards.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds minimal behavioral context beyond that—only the scoping to 'within one project' (already in schema) and the notion of returning summaries. No contradictions; it earns a baseline 3 because it adds little extra but doesn't need to.

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 zero fluff. The primary purpose is front-loaded, and the routing guidance is appended as a separate, clearly scoped sentence. Every word earns its place.

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

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

For a 4-param tool with one required param and a low schema coverage, the description covers the core use case and routing but omits pagination semantics. However, an output schema exists, so return values are handled elsewhere. The missing param details are a minor gap given the explicit routing and annotations.

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 25% (only projectId is described). The description clarifies searchQuery as 'full-text query' but leaves limit and offset entirely unexplained. Since coverage is low, the description should compensate more; it only partially does, so a 2 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 states a clear verb ('Find'), resource ('issue summaries'), and method ('full-text query'), plus an optional scope ('within one project'). It explicitly distinguishes itself from listIssues (exact-field/saved-query/custom-field filtering) and getIssue (inspect result), so an agent can select it correctly without opening 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?

The description gives explicit routing: use listIssues for structured filters and getIssue for details, implying searchIssues is for full-text search. It names alternatives and conditions, leaving no ambiguity about when to invoke 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 establish readOnly, idempotent, open-world, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context: full-text content matching, optional cross-project scope, and the fact that it only returns wiki pages—without contradicting the 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?

Two compact sentences with no filler; the primary action is front-loaded and the alternative routing is stated immediately after. Every sentence earns its place.

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

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

For a read-only search tool with robust annotations and an output schema, the description covers what it searches, the optional scope, and how to follow up on results. Nothing essential is missing for correct invocation.

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 schema description coverage at only 25%, the description must compensate. It clarifies searchQuery as a full-text content query and projectId as an optional scope control ('across all accessible projects'), but limit and offset receive no added semantics beyond their standard names.

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

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

Description opens with a specific verb and resource ('Find project wiki pages') and identifies the query mechanism as full-text content search. It further scopes the tool to wiki content and explicitly names getWikiPage and searchAll in the next sentence, making differentiation from siblings clear.

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 alternatives with conditions: use getWikiPage to read a selected result, and use searchAll when non-wiki content should also match. The 'optionally across all accessible projects' phrasing also clarifies project scoping behavior.

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 openWorldHint=true, so the safety profile is covered. The description adds genuine value by clarifying PATCH semantics ('omitted fields remain unchanged') and the journal-entry limitation, though it omits permission requirements and failure modes.

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, both earning their place. The mutation contract is front-loaded and the sibling routing follows immediately with 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?

Return values are covered by the output schema, and for a 17-parameter mutation the key semantic (partial update, one issue) is stated. It is slightly thin on caveats such as permission needs, validation errors, and the customFieldsJson encoding, which the schema only briefly 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 coverage is 71% and the schema documents formats, clearing conventions, and lookup-tool provenance. The description contributes the important partial-update contract (omitted fields unchanged) but gives no per-parameter guidance beyond that, which matches the baseline when the schema does most of the work.

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 (Modify) and resource (one existing Redmine issue), and explicitly scopes behavior to 'only the supplied fields'. It also names a sibling (addIssueNote) and excludes journal editing, which disambiguates it from the write-oriented 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 a clear routing rule: use addIssueNote for comment-only changes. It also states a when-not ('does not edit existing journal entries'). It stops short of covering other near neighbors like createIssue or getIssueJournal, 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.