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

Annotations only declare the safety profile (readOnlyHint, idempotentHint, destructiveHint), which the description does not simply repeat. Instead it adds non-blocking semantics ('returns immediately'), the out-of-band user interaction model in the system browser, and a security guardrail against collecting secrets in-conversation — all behavior an agent could not infer from 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?

Three sentences, front-loaded with the action and the immediate-return fact, then the follow-up routing, then the guardrail. No filler and no repetition of the title.

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

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

For a no-argument flow-initiation tool with no output schema, the description covers what the agent must do before, during, and after the call. It does slightly under-specify what the tool returns (e.g. a URL, a pending state, or an error when no browser is available), which matters more given there is no 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?

There is a single optional parameter ('scopes') with 100% schema description coverage, including an example and the incremental-consent behavior on re-run. The description adds nothing about it, so the schema carries the load; baseline 3 applies.

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

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

States a specific verb and resource ('Starts a Redmine OAuth2 sign-in in the system browser') plus the key behavioral fact that it returns immediately. It is unmistakably distinct from the sibling auth_login_status, which it names as the follow-up step.

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

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

Gives explicit sequencing guidance: 'Ask the user to finish there, then call auth_login_status,' and a hard negative constraint ('Never ask for credentials, an API key, or an authorization code'). It does not state the when-not case (e.g. that the agent should not call this at all if a session is already valid), so it falls just short of full alternatives coverage.

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 the bar is low; the description still adds real value by disclosing that a failure state includes 'the fix' (remediation guidance in the response) and by explicitly stating 'Never returns a token,' which is a meaningful security assurance for an auth tool.

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

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

A single front-loaded sentence that lists the possible states first and closes with the key caveat. Every clause earns its place 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?

With no output schema, the description carries the return-value burden and largely does so by naming the three terminal states and noting that failures include remediation. It is nearly complete, though it doesn't indicate whether the status is transient (i.e., whether the agent should poll repeatedly) or describe any rate/retry behavior.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds nothing about inputs because there are none, and the empty schema is consistent with that.

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

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

States a specific verb ('Reports') and resource ('background browser sign-in') and enumerates the three possible outcomes (pending, signed in, failed). It implicitly separates itself from auth_begin_login, but it never names or contrasts with the nearby session_status sibling, so an agent must still infer which status tool to call.

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 phrase 'where the background browser sign-in has got to' implies this is a polling/status-check tool to be used after starting sign-in, but it never explicitly says when to use it, when not to, or that auth_begin_login is the initiating counterpart. Usage is only implied.

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, but the description adds real behavioral detail beyond them: the return shape (base64 bytes plus metadata), automatic decoding of text files, and the refusal path when a file exceeds maxBytes. That refusal semantics is the kind of thing an agent cannot get from the schema or 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?

Three short sentences, zero filler, and the primary behavior (returns base64 + metadata) is front-loaded. Each sentence contributes distinct information.

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

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

No output schema exists, but the description compensates by describing the return payload (base64 bytes, metadata, decoded text) and the limit-exceeded response. The only missing piece is routing relative to files_get_attachment.

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% (both 'id' and 'maxBytes' are documented in the schema, including the default and cap), so the baseline is 3. The description reinforces maxBytes' effect ('refuses files over maxBytes with metadata only') but adds no format or syntax beyond what the schema 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+resource ('Downloads an attachment'), so the agent knows exactly what it does. It does not, however, distinguish itself from the sibling 'files_get_attachment', which sounds like an overlapping retrieval tool — that ambiguity is left unresolved.

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

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

There is no when-to-use / when-not-to-use guidance and no reference to alternatives such as files_get_attachment or files_list_project_files. The agent must infer from the name alone that this is the byte-fetching tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine value beyond that by disclosing the return payload (filename, size, content type, download URL), which matters here because no output schema exists. It still omits error behavior and whether the download URL is authenticated or expiring.

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

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

A single front-loaded sentence with no filler. Minor deduction for the awkward phrasing 'Returns one attachment metadata', which reads clumsily but does not obscure meaning.

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 trivial one-parameter read tool, the combination of schema, annotations and the enumerated return fields covers nearly everything an agent needs. What is missing is how to source the id and any failure mode, both minor for this tool class.

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?

Only one parameter exists and schema description coverage is 100%, so the schema fully documents 'id'. The description adds nothing about where to obtain the id (e.g., from a file listing) or its format, so the baseline 3 applies.

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

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

States a specific verb and resource: returns metadata for a single attachment, and enumerates the fields returned. It implicitly distinguishes itself from siblings like files_download (content) and files_list_project_files (list), but never names those distinctions explicitly.

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

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

There is no when-to-use guidance and no routing to alternatives, even though files_download is an obvious sibling an agent could confuse this with. The agent must infer from the name alone that this is the metadata-only call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered without the description's help. The description adds the version requirement (Redmine 7.1+), which is useful, but says nothing about pagination, result count, or return shape for a list operation.

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

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

Two short sentences with zero filler; the core purpose is front-loaded and the version constraint follows immediately. Nothing is wasted or redundant.

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

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

For a simple read-only list tool with full annotation coverage and a fully documented single parameter, the description is nearly sufficient. But the unresolved overlap with files_list_project_files leaves a real selection ambiguity that the description should have resolved.

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

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

Schema description coverage is 100% and the single project_id parameter is documented as 'Project id or identifier', so the baseline is 3. The description adds no syntax or format detail beyond what the schema already supplies.

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 ('Lists') and resource ('documents of a project's Documents module'), so the basic purpose is unambiguous. However, it never distinguishes itself from the sibling files_list_project_files, which sounds like it could cover the same ground, forcing the agent to guess between the two.

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

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

The description provides a prerequisite ('Needs Redmine 7.1+'), which is a genuine usage constraint, but it gives no when-to-use/when-not guidance and never names files_list_project_files as the alternative. Usage is only implied by the resource phrasing.

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 externally. The description adds nothing beyond that: no pagination behavior, no result ordering, no permission requirements, and no note on whether the listing is scoped to a module or returns everything.

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 short sentence with no filler and the resource front-loaded. It is efficient, though so terse that it arguably under-specifies rather than being a model of structured communication.

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

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

For a simple read-only list tool with a fully documented schema and annotations covering safety, the essentials are present. What is missing is list-specific behavior (pagination, result count, ordering) that an agent would want before invoking it repeatedly.

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

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

Schema description coverage is 100% and the single project_id parameter is documented as 'Project id or identifier.' The description adds no extra meaning about the identifier format or accepted values, so the baseline 3 for fully-covered schemas 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?

Names a specific verb (Lists) and resource (files attached to a project's Files module), which is clearer than a bare 'list files'. However it does not distinguish itself from near-siblings like files_list_documents, files_download, or files_get_attachment, so the agent must still infer which listing tool applies.

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

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

There is no when-to-use guidance, no mention of when NOT to use it, and no alternative tool is named despite several file-related siblings. The agent gets no help routing between files_list_project_files, files_list_documents, and files_get_attachment.

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

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

Annotations declare non-read-only and non-idempotent, and the description adds genuinely useful behavioral context beyond that: the return artifact is a token, it must be consumed via the uploads array, and it expires with the session. Token expiry is a real operational constraint the schema and annotations do not convey.

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

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

Three short sentences, zero filler, front-loaded with the action and its return value. Every sentence carries distinct information (what it does, how to use the token, when the token dies).

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

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

There is no output schema, yet the description still explains the return value (an upload token) and how to use it, which is the critical missing piece. Combined with the fully documented parameters and annotations, nothing an agent needs to call this correctly is absent.

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

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

Schema description coverage is 100%, so filename, content_type, and content_base64 are already documented in the schema. The description only echoes "filename" inside the uploads array and adds no format or constraint detail beyond the structured fields, so baseline 3 applies.

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

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

States a specific verb ("Uploads") and resource ("raw bytes") and immediately names the artifact it produces ("upload token"). It is clearly distinguishable from siblings like files_download and files_get_attachment.

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 how to consume the result — reference it from issues_create or issues_update via uploads: [{token, filename}]. It gives clear downstream context but does not spell out when to prefer this upload path over anything else or state preconditions.

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, so the safety profile is partly covered. The description adds that the operation is additive/append-only and leaves other data untouched, but omits permissions, response shape, and any note-visibility behavior beyond the schema's private_notes flag.

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

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

A single sentence that front-loads the action and immediately qualifies scope. Every clause earns its place with no redundancy.

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

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

For a simple three-parameter append tool with full schema coverage and annotations covering the safety profile, the description is sufficient, and an output schema is absent so return values need no explanation. It could say slightly more about whether private notes are visible to the issue author, but 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%, so all three parameters (id, notes, private_notes) are documented in the schema. The description adds no parameter-level detail, so this sits at the baseline where the schema does the heavy lifting.

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 ('Appends a journal note to an issue') plus a behavioral scope clause ('without changing anything else') that distinguishes it from the mutation-oriented siblings like issues_update and issues_create. It does not name a sibling explicitly, but the delta is 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?

Use is implied: reach for this when you want to add commentary rather than modify issue fields, which is why it is separate from issues_update. There is no explicit when-to-use, when-not, or named alternative, so guidance stops at inference level.

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, so the mutation/non-idempotent profile is covered. The description usefully adds that the call returns the created issue including its id, which tells the agent how to chain follow-up calls, but says nothing about required permissions, validation errors, or defaults (e.g. tracker defaulting, Textile body).

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, both front-loaded and free of filler; the return-value note is placed where it reads naturally. It borders on too terse for a 17-parameter mutation, but no sentence is wasted.

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

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

Annotations cover the safety profile and the schema fully documents all 17 fields, so the description only needs to frame the operation and its outcome — which it partially does. It omits any warning about attachments requiring a prior files_upload call and gives no hint about failure modes, leaving the definition minimally adequate for a create operation of this complexity.

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

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

Schema description coverage is 100% across all 17 parameters, including non-obvious ones like uploads tokens from files_upload and assignee resolution to an id. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ("Creates an issue in a project") and adds the return value ("Returns the created issue (with its id)"). It is clearly distinguishable from siblings like issues_update or issues_add_note by name, but never explicitly contrasts with them.

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

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

There is no guidance on when to use this versus issues_update (for modifying an existing issue) or issues_add_note (for commenting). No prerequisites, permissions, or exclusions are mentioned, so the agent must infer routing from the tool name alone.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that – it does not say what happens if the relation already exists (relevant for a non-idempotent create) or what errors to expect.

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 short sentence that front-loads the action and resource with zero waste. Brevity is appropriate here, though the ellipsis-truncated type list is slightly informal.

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 non-idempotent mutation with a fully documented schema and annotations present, the minimum viable bar is met, but the description omits any mention of duplicate-relation behavior or failure modes an agent would want before calling a create.

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

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

Schema description coverage is 100%, so all four parameters including the enum and the delay field are already documented in the schema. The description merely echoes the relation-type values that the schema enum already lists, adding no syntax or format detail.

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 (links) and resource (two issues) with examples of relation types, so the agent can tell it apart from issues_list_relations and issues_delete_relation. It does not explicitly name those siblings, but the create-a-relation action is unambiguous.

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

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

No guidance on when to use this versus alternatives such as issues_delete_relation or issues_list_relations, and no prerequisites mentioned. The reader must infer usage entirely from the name.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is largely covered structurally. The description adds useful irreversibility context ('cannot be undone') but omits the practical consequence of non-idempotency — e.g. that a repeat call on an already-deleted id will fail — and says nothing about permissions or error behavior.

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

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

Two short sentences, zero padding, with the destructive consequence front-loaded right after the action statement. 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 simple single-parameter delete, the description plus annotations cover the essential facts: what it does, what it affects, and that it is irreversible. Minor gaps remain around failure modes (nonexistent id, permission errors), but nothing an agent needs to invoke it correctly is missing.

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

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

There is a single required parameter with 100% schema description coverage ('Issue id.'), so the schema fully documents the input. The description adds no extra meaning about the id (e.g. where to obtain it), leaving this at the baseline for fully-covered schemas.

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

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

States a specific verb and resource ('Deletes an issue'), making it immediately distinguishable from siblings like issues_get, issues_update, and issues_create. It does not, however, explicitly name or route against any sibling.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites, and no note about what to do for soft-delete/close scenarios that issues_update might serve. The agent must infer usage entirely.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond restating the removal, giving no information about irreversibility, side effects on the related issues, or error behavior when the relation id is unknown.

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

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

A single front-loaded sentence with the acting verb and the identifying parameter, no filler and no redundancy. Appropriately sized for a one-parameter delete operation.

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 destructive delete with full annotation coverage and a 100% documented schema, the description covers what the tool does and which identifier to supply. Only minor items are missing, such as confirmation of irreversibility or behavior on a non-existent relation id.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'Relation id (not an issue id)'. The description's phrase 'by its relation id' merely echoes the schema, which is the expected baseline when the schema carries the parameter semantics.

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

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

States a specific verb ('Removes') and resource ('an issue relation') scoped to a relation id, so the agent can tell it acts on relations rather than issues. It does not explicitly contrast itself with close siblings like issues_delete, issues_list_relations, or issues_create_relation, but the resource noun is unambiguous.

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

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

There is no when-to-use guidance, no prerequisite (e.g., that the relation must exist), and no mention of alternatives such as issues_delete for removing issues themselves. The agent must infer the usage context entirely from the name and sibling list.

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=false), so the description's added value is the 403 semantics — explaining that permission-shaped failures are indistinguishable from not-found and should not be retried. That is exactly the kind of context annotations cannot express. It stops short of describing include-failure behavior or result size, hence not 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, both load-bearing: the first establishes what is returned, the second prevents a wasted retry loop. The core behavior is front-loaded with zero preamble.

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, return values need not be explained, and the description correctly focuses on the 403 edge case instead. The only minor gap is not enumerating include options or noting what happens with an invalid id versus a forbidden 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?

Schema description coverage is 100%, so both parameters are documented in the schema already. The description only implies the include parameter's purpose ('optional associated data via include') and defers to issues_list for valid values, adding no real syntax beyond the schema.

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

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

States a specific verb and resource — 'Returns one issue by id' — with the optional include expansion, which cleanly contrasts with the sibling issues_list that returns many. An agent can distinguish the single-fetch from list/search tools 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?

Gives concrete failure-path guidance: on 403 the issue is in an invisible project or private to someone else, and it names users_my_access as the alternative action rather than retrying. It does not cover other cases (e.g., wrong id vs. missing issue, or when to prefer issues_list), but the guidance it does give is actionable and non-obvious.

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

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

The annotations already declare it as a safe, idempotent read. The description adds that results are paged with a total_count, but that behaviour is largely restated by the 'limit'/'offset' schema descriptions, and it omits notable traits such as the subject filter being applied client-side after fetching.

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, front-loaded with the core action and scope, with the pagination caveat last. Nothing is redundant or padded.

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, a full schema, and an output schema, the description need only orient the agent, which it does. A brief note on when to choose this over the related get/query tools would close the remaining 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 100%, so every parameter is already documented with types and accepted values. The description lists filter categories (project, tracker, status, assignee, saved query) that map onto those parameters but adds no syntax or resolution detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Lists issues') and enumerates the filter axes it accepts, so an agent knows exactly what it returns. It does not explicitly distinguish itself from nearby siblings like issues_get, queries_run, or search_query, which leaves some routing ambiguity.

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

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

The clause 'pass offset to walk further pages' is real usage guidance for pagination, but there is no statement of when to prefer this over issues_get or queries_run. Usage is implied by the tool's name and filter list rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing behavioral beyond that — no pagination, no return shape, no ordering or grouping of the relation types.

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

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

One short sentence with zero filler and the resource stated up front. It is appropriately sized for a trivial read, though it is arguably too sparse to convey return expectations.

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

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

For a one-parameter read tool with annotations carrying the safety profile, the essentials are present. However, with no output schema, the description should have said something about the returned structure (e.g., grouped by relation type, direction of the relation), which it leaves unspecified.

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?

Single parameter with 100% schema description coverage ('Issue id.'), so the schema fully documents it. The description adds no extra meaning (e.g., whether it's the local issue whose relations are returned vs. the related issue), so baseline 3 applies.

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

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

Clear verb+resource ('Lists the relations ... of an issue') with illustrative relation types (blocks, duplicates), which cleanly separates it from issues_list, issues_get, and issues_create_relation. It does not explicitly name a sibling, so it stops short of a 5.

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

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

No statement of when to use this versus issues_get (which may also surface relations) or issues_create_relation / issues_delete_relation for mutation. The reader must infer usage entirely from the name and one-line description.

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 non-read-only, idempotent, non-destructive, so the safety profile is covered. The description adds genuine unannotated context — that unspecified fields are preserved and that notes appends a journal entry — but says nothing about permissions, validation failures, or whether fields can be cleared (e.g. null/empty sentinels).

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 clauses with the partial-update rule front-loaded and no filler; an agent gets the essential semantics in one 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?

A 17-parameter mutation tool at 24% schema coverage with no output schema and no mention of return behavior or error conditions; the description is far too thin for this surface area, leaving most parameters' semantics unknown.

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 17 parameters and only 24% schema coverage, the description must compensate, yet it explains only the notes parameter. The numerous *_id fields, date formats, custom_fields array shape, and the string form of assigned_to_id (e.g. 'me' vs numeric id) go undocumented in either place.

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 plus the key semantic 'only the fields passed change', which distinguishes it from a full-replace update. It does not differentiate from the very similar sibling issues_add_note, which also appends a journal entry, leaving overlap an agent must resolve on its own.

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 partial-update rule implies how to use it (pass only what changes), but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as issues_add_note for note-only writes or issues_create for new issues.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not say what happens when the user is already a member (relevant given the idempotent claim), whether permissions are required, or what the response contains.

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 efficient sentence with no filler, and the core action is front-loaded. It is arguably too terse for a mutation tool, but nothing in it is wasted.

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

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

The tool is simple (3 required params, no nesting, no output schema) and annotations cover the safety profile, so the description is minimally adequate. Still, it omits duplicate-member behavior and permission prerequisites that would matter for a membership mutation.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema, so the schema does the heavy lifting. The phrase 'with the given roles' only loosely restates role_ids and adds no format or constraint detail (e.g. that at least one role is required, per minItems).

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 (Adds) and resource (a user to a project) plus the role payload, so the operation is unambiguous. It does not explicitly distinguish itself from close siblings like projects_update_member or projects_remove_member, though the name largely does that work.

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

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

There is no when-to-use guidance and no mention of alternatives, even though projects_update_member and projects_remove_member sit directly alongside it in the sibling list. An agent gets no help choosing between adding and updating a membership.

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, so the write-but-non-destructive profile is covered. The description adds only the return-shape fact ('with its id'), and says nothing about required permissions, duplicate-identifier failures, or what happens to inherited members/modules.

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

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

Two short sentences, front-loaded with the action, with no filler. It is efficient, though the brevity comes at the cost of usefulness rather than being a model of tight scoping.

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

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

For a 9-parameter mutation tool with 44% schema coverage and no output schema, the description covers only what the tool does and its return shape. It omits the creation semantics (uniqueness of identifier, visibility default), permission needs, and how the many optional fields affect the created project.

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 44% across 9 parameters, so the description is expected to compensate and does not. It mentions no parameter at all — not even the required name/identifier or the meaning of parent_id, tracker_ids, inherit_members or enabled_module_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?

States a specific verb and resource ('Creates a project') and notes the return value. It is clearly distinguishable from siblings like projects_list, projects_get and projects_update, but never names or contrasts them explicitly.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives or related tools. The agent must infer that this is the write-path counterpart to projects_list/projects_get/projects_update on its own.

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 only that associated data is optional, contributing little behavioral context beyond the structured fields, and says nothing about error behavior for a missing id.

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

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

A single short sentence with the resource and lookup key front-loaded and no filler. It is appropriately sized, though the phrase 'optional associated data' is slightly vague for the space it occupies.

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

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

For a two-parameter read tool with full schema coverage and annotations, the description is close to sufficient, but the include parameter's accepted values are only deferred to 'see projects_list', leaving the caller without a concrete list. No output schema exists, so return shape is not covered either.

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

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

Schema description coverage is 100%, so the schema already documents both parameters; baseline 3 applies. The description's 'by id or identifier' and 'optional associated data' merely restate what the schema fields say, adding no syntax or valid-value detail.

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 ('Returns one project') and the lookup keys ('by id or identifier'), which implicitly distinguishes it from the list-style sibling projects_list. It stops short of explicitly naming that sibling or any other alternative.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative is named. An agent must infer that this is the single-record lookup versus projects_list on its own, which is the same gap seen in the mid-tier calibration example.

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 only adds that a page and total_count are returned, which is largely covered by the output schema, and says nothing about how visibility is determined or what `include` changes.

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

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

Two short sentences, front-loaded with the core purpose and followed by return-shape context. No wasted verbiage.

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 simple, has an output schema, full parameter documentation, and read-only annotations, so the description covers the essentials. It still omits visibility rules and any guidance on `include` or pagination, keeping it short of fully complete.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description adds no parameter-level meaning beyond that 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?

The description states a specific verb and resource ('Lists visible projects') and adds scope ('visible'). It does not distinguish itself from nearby siblings such as projects_get or projects_list_memberships, so it is clear but not fully differentiated.

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

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

Usage is implied by the name and by 'visible projects', but there is no explicit guidance on when to choose this over projects_get, projects_list_memberships, or search_query. Pagination strategy and inclusion choices are left entirely to the schema.

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

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

The annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds only what fields are returned (ids and assignees), which is useful but does not disclose additional behavioral traits such as permissions, pagination, or ordering.

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, front-loaded sentence that states the action, resource, and return fields with zero waste.

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

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

For a simple read-only list tool with one fully documented parameter and rich safety annotations, the description is nearly complete. It states what is returned, though it omits any usage context that would help route the agent among 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?

Schema description coverage is 100%, with project_id fully documented as 'Project id or identifier.' The description adds no extra parameter meaning, so the baseline of 3 applies.

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

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

The description states a specific verb ('Lists') and resource ('issue categories of a project'), and it clarifies the returned fields ('ids and assignees'). It does not explicitly distinguish this tool from siblings such as projects_get or issues_list, so it falls short of a 5.

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

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

The description gives no when-to-use guidance, no exclusions, and no mention of alternative tools. The agent must infer that this is the right tool when issue categories are needed.

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 only that roles are included in the result; it says nothing about pagination behavior despite limit/offset parameters, which is the main behavioral gap.

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

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

A single front-loaded sentence with zero waste and the key noun (members, roles) up front. It is appropriately sized for a simple list tool, though it is arguably too terse to earn a 5.

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

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

For a simple read-only list operation with annotations covering safety, the definition is nearly sufficient, but it omits pagination semantics and any hint about the shape of a membership record. Nothing is misleading, but an agent gets no help beyond the bare purpose.

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%: project_id is documented, but limit and offset are not described anywhere. The description adds no parameter meaning at all (no mention of paging, defaults, or the project_id format), so it fails to compensate 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 (lists members of a project) and clarifies the payload includes roles. It is distinguishable from siblings like projects_list and projects_get, though it never explicitly names them.

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

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

No when-to-use guidance is given. Nothing tells the agent how this differs from projects_list_categories, projects_get, or the member-mutation siblings (projects_add_member/update_member/remove_member), nor what prerequisite (project_id) 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=false, idempotentHint=false, destructiveHint=false, so the agent knows the safety profile. The description adds nothing beyond them: it does not say whether the removal revokes the user's roles/project access, whether it can be undone or re-added, what errors occur for an unknown id, or how it relates to projects_add_member. Note a mild tension between 'Removes' and destructiveHint=false, but readOnlyHint correctly marks this as a write.

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

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

A single front-loaded sentence with zero filler. The verb and the disambiguating argument framing come first, so nothing needs to be skimmed past.

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 simple (one parameter, full schema coverage, annotations present, no output schema), so little prose is strictly required. However, it omits the practical prerequisite of where a membership id comes from and the side effect of the member losing project access, leaving a real gap 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?

Schema description coverage is 100%, and the schema already documents the single parameter as 'Membership id (not a user id)'. The description's 'by its membership id' merely restates that, adding no format, source, or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Removes) and resource (project membership) plus the identifying argument, so the agent knows exactly what operation occurs. It does not explicitly differentiate itself from siblings like projects_add_member, projects_update_member, or projects_list_memberships, and it never says an update_member with empty roles is an alternative removal path.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternatives. The phrase 'by its membership id' faintly implies the id must come from projects_list_memberships, but this is left entirely to inference, and no exclusion or edge-case guidance is provided.

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=true, and destructiveHint=false. The description adds genuine value by disclosing PATCH-style semantics ('only the fields passed change'), which is not derivable from the annotations. However, it says nothing about permissions, validation failures, or effects on unspecified fields beyond the one clause.

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 short sentence with the key partial-update constraint front-loaded and no filler. It is dense and efficient, though very sparse for a 7-parameter mutation.

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

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

For a 7-parameter mutation with no output schema and 14% schema coverage, the description should carry much more weight. It gives only partial-update semantics, leaving the meaning of each field, permission requirements, and outcomes unspecified.

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 14% — only 'id' is documented, leaving name, homepage, is_public, description, tracker_ids, and enabled_module_names undocumented. The description's mention of 'fields passed' gives a general mental model but no per-parameter meaning, so it does not compensate 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?

States a specific verb (updates) and resource (project attributes), and the clause 'only the fields passed change' clarifies the partial-update semantics. It does not differentiate from siblings like projects_update_member or projects_add_member, so it stops short of a 5.

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

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

No guidance on when to use this tool versus alternatives such as projects_create, projects_update_member, or projects_add_member. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, and the word 'Sets' is consistent with set/replace idempotent semantics. However, the description doesn't disclose that setting roles likely replaces existing role assignments, nor any permission requirements -- context that matters for a mutation tool.

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

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

A single tight sentence with the resource and operation front-loaded and no filler. It is appropriately sized, though its brevity comes at the cost of the missing usage and behavior details noted elsewhere.

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

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

With 2 fully documented params, annotations covering the safety profile, and no output schema, the definition is minimally adequate. But for a role-mutation tool it omits the replace-vs-append semantics of role_ids and the required membership-id resolution step, leaving real gaps.

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

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

Schema description coverage is 100%, with 'Membership id (not a user id).' and 'Role ids to set.' already in the schema. The description adds nothing beyond that baseline; it doesn't clarify whether role_ids replaces or appends to existing roles.

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: 'Sets the roles of a project membership by its membership id.' That is clear and distinguishable from add_member/remove_member, though it never explicitly names those siblings or contrasts the membership-id vs user-id targeting it uses.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g. you must first resolve a membership id via projects_list_memberships), and no routing against alternatives like projects_add_member or projects_remove_member. Usage can only be inferred from the name.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds the useful behavioral detail that only 'visible' queries are returned, implying permission-scoped results, but says nothing about ordering, pagination behavior, or result size defaults.

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 the resource and the scoping qualifier front-loaded and no filler. Nothing needs to be cut.

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

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

For a simple read-only list tool with no output schema, the description identifies what is returned, but leaves the undocumented limit/offset semantics and pagination behavior unexplained. Adequate at minimum but with a real gap for the only two inputs.

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

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

Schema description coverage is 0% for both limit and offset, so the description carries the full burden and does not address them at all. The phrase 'filters and columns' describes returned fields, not the input parameters, so it does not compensate 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?

States a specific verb and resource ('Lists the visible saved issue queries') and adds scope detail ('with their filters and columns'), making clear it enumerates definitions rather than executing them. It stops short of explicitly naming the sibling queries_run, so the read-vs-run distinction must be inferred.

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

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

There is no when-to-use guidance, no condition that selects this tool over queries_run, and no mention of pagination or result-set expectations. The agent gets a purpose but no routing advice.

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 contributes useful context by stating the return shape (matching issues plus total_count), but says nothing about pagination behavior despite limit/offset parameters.

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, information-dense sentence that front-loads the action and the result. Zero wasted words.

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

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

For a simple read tool whose annotations already cover safety, the description is adequate but leaves gaps: no guidance on sourcing query_id, and no explanation of limit/offset pagination semantics, which matter because there is no 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 only 33%: query_id is documented in the schema, but limit and offset have no descriptions in either the schema or the description. The description mentions no parameters at all, so it fails to compensate for the coverage gap on the pagination 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+resource ('Runs a saved issue query') and even names the return payload ('matching issues plus total_count'). It is clear what the tool does, though it does not explicitly differentiate itself from siblings like queries_list or search_query.

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

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

No when-to-use or when-not-to-use guidance is given. The agent is not told that query_id must come from queries_list, nor when this beats issues_list or search_query. Usage is only faintly implied by 'saved issue query'.

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 useful content beyond that: it enumerates what the output contains (tool groups, scopes, enabled flags) and frames the tool as a 403 diagnostic, which complements 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 short sentences with zero filler. The content description leads and the usage trigger follows, so both the what and the when are 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?

There is no output schema, so the description carries the return-value burden, and it does list the three categories of data returned. It stops short of describing format or whether the list is exhaustive, leaving a small gap for a diagnostic tool an agent may call on error paths.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a no-parameter tool is 4, and no parameter-related confusion is introduced.

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 precise verb and resource (lists tool groups, their required Redmine permission scopes, and enabled state), which is far more specific than the title alone. No sibling tool covers permissions, so it is easily distinguished from the surrounding issue/project/wiki 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 first call when something returns 403" gives an explicit, actionable trigger for when to reach for this tool. It does not name alternative tools or describe when not to use it, but the diagnostic condition is clear enough to guide invocation.

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

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

Adds real behavioral context beyond the annotations: GET is the default and write methods are gated behind a --allow-generic-write flag, which is an operational prerequisite the annotations don't convey. It also states requests run under the signed-in credential. It does not spell out what a destructive write can damage, 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 tight sentences: the identity of the tool is front-loaded, followed by the routing advice and the write gate. No filler, no repetition.

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

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

For a 4-param generic REST proxy with no output schema, the description covers the essentials: scope, default method, and the write authorization gate. Minor gaps around error behavior on raw calls (the description only says typed tools explain errors better) keep it from a 5.

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 path format, method enum, and body/query are already documented. The description only restates the GET default and write-gating that the schema's own method/body descriptions already carry, adding little new syntax or format 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?

Opens with a specific metaphor-plus-scope: an 'escape hatch: any Redmine REST path with the signed-in credential.' An agent immediately knows this is the generic fallback versus the typed siblings, and the description names that distinction explicitly ('Prefer the typed 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?

Tells the agent when not to use it ('Prefer the typed tools: they page, project, and explain errors') and gives concrete reasons for that preference. Lacks an explicit trigger for when the escape hatch IS the right choice, but the 'any Redmine REST path' scope implies it well.

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 the safety profile. The description adds value by disclosing the return shape (ranked results with type, title, excerpt), but says nothing about pagination behavior, result caps, or auth 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?

Two tight sentences, front-loaded with the verb and scope, then the return format. Every clause earns its place 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?

For a global search tool with 4 params and no output schema, the description adequately covers purpose and result shape. However, pagination (limit/offset) and result-ranking behavior are left unexplained, and no guidance is given on interacting with the many sibling list/query 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?

Schema coverage is 50%: q and scope are documented in the schema, while limit and offset are not. The description's enumeration of searchable domains loosely maps to the scope parameter, but it adds no syntax or meaning for limit/offset, 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?

States a specific verb (searches) and enumerates the resources covered (issues, wiki pages, documents, files, news), so an agent immediately understands the scope. There is no competing search tool among the siblings, so differentiation isn't needed, but the description doesn't explicitly claim global coverage vs. filtered alternatives beyond the 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?

The description explains what the tool does but never states when to use it versus alternatives like queries_run or the various *_list tools. There is no when-to-use, when-not-to-use, or precondition guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: that it performs a live network probe (GET /users/current.json) rather than only reading cache, and that it surfaces a consent checklist. It does not describe failure behavior or output shape.

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, with the actionable directive ('Call once first') front-loaded ahead of the payload description. Every clause carries information; nothing is padding.

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

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

There is no output schema, so the description must carry the return-value burden, and it does: it names the cached account, reachability result, and consent checklist. For a zero-parameter diagnostic tool with full annotation coverage, nothing an agent needs in order to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. Schema coverage is 100% and empty, so no compensation is needed.

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

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

The description names a specific resource (session status) and enumerates the three things it reports: the cached account, Redmine reachability via a live GET /users/current.json, and the consent checklist. That is far more concrete than a tautology. It stops short of naming or distinguishing itself from look-alike siblings such as auth_login_status or users_get_current, which keeps it out of 5 territory.

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?

'Call once first' is an explicit, actionable timing directive that tells the agent to run this before anything else and not to repeat it. It does not state when not to use it or point to alternative status/auth tools, so it lacks the exclusions a 5 requires.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered by structured data. The description adds the irreversibility caveat ('cannot be undone'), which is genuinely useful, but says nothing about the non-idempotent behavior (repeated calls failing) that idempotentHint=false implies.

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, action stated first and the risk caveat second. Nothing extraneous; 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 single-parameter destructive delete with annotations covering the safety profile and a fully documented schema, the description covers what an agent needs. It could still note required permissions or error behavior, but 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% and the single 'id' parameter is documented in the schema as the time entry id. The description adds no additional meaning about the identifier, so the baseline of 3 for fully-covered schemas applies.

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

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

States a specific verb and resource ('Deletes a time entry'), which cleanly separates it from siblings like time_update_entry or time_log. It does not explicitly name a sibling, so it stops short of the 5 tier.

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

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

No indication of when to use this versus time_update_entry (which could zero out or move an entry) or any prerequisites such as ownership or admin rights. The agent must infer the usage context entirely from the tool name.

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 by structured data. The description adds only that results carry ids, which is modest extra context for a read-only lookup; no auth, caching, or ordering behavior is described.

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 tight sentence that front-loads the verb and resource with zero filler. Nothing could be trimmed without losing information.

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

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

With no output schema, the description carries the burden of describing the return shape, and it only partially does so (ids, example names). For a trivial parameterless reference-list tool this is minimally adequate, but it does not say whether other fields, sorting, or completeness are guaranteed.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description's mention of ids refers to return values rather than inputs and therefore neither helps nor harms parameter understanding.

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

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

The description gives a specific verb ("Lists") and a precise resource ("time-tracking activities"), even naming example values (Design, Development) and noting that ids are returned. It is clearly distinguishable from siblings like time_list_entries and time_log, though it does not explicitly contrast itself with them.

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

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

There is no statement of when to call this tool, what it is a prerequisite for (e.g. obtaining activity ids for time_log or time_update_entry), or which alternative to prefer. Usage can only be inferred from the name and the mention of ids.

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 and the bar is lower. The description adds no behavioral context beyond that — no pagination behavior, no note that limit is capped at 100, no indication of result ordering — but it does not contradict the annotations either.

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

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

A single front-loaded sentence with zero waste and the resource stated first. It is efficient, though the extreme brevity means the freed space is not used for any useful extra context.

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 list tool with no output schema and annotations carrying the safety profile, the description covers what the tool returns and the axes it can be scoped by. Missing pagination notes are a minor gap given limit/offset defaults are visible in the schema.

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

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

Schema coverage is 71%, in the middle band, and the schema itself documents from/to, user_id, issue_id, and project_id. The description conceptually groups those same filter axes but adds no syntax, defaults, or semantics beyond them, and the two pagination parameters (limit, offset) are undocumented in both places.

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

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

The description states a specific verb ('Lists') and resource ('time entries') and enumerates the available filter axes, which matches the schema's filter parameters. It does not explicitly distinguish itself from siblings such as time_list_activities or time_log, so it stops short of a 5.

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

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

Usage is implied by the filter enumeration ('filtered by issue, project, user, or date range'), which tells an agent this is the read/query tool versus time_log/time_update_entry/time_delete_entry. However, there is no explicit when-to-use guidance, no mention of when NOT to use it, and no pointer to the alternative for activity types.

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, so the write/no-idempotency profile is covered structurally. The description usefully adds that a new entry is created and returns an id, which implies repeat calls create duplicates, but it says nothing about permissions or duplicate-submission risk.

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

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

Two sentences, zero filler, with the action front-loaded and the return value second. Nothing could be trimmed without losing information.

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

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

For a mutation with no output schema, it at least tells the agent what comes back (the created entry and its id). With fully documented params and annotation-covered safety, the only real gap is the one-of issue_id/project_id requirement and non-idempotent duplication behavior.

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

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

Schema description coverage is 100%, so all six parameters (hours, comments, issue_id, project_id, spent_on, activity_id) already carry their own descriptions and defaults. The description adds no formatting, validation, or mutually-exclusive-field detail beyond that 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 ('Logs time on an issue or a project') and adds the outcome ('Returns the created entry (with its id)'), which cleanly separates it from time_list_entries and time_update_entry. It never names a sibling or explicit boundary, so it stops short of a 5.

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

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

No when-to-use guidance, no mention of alternatives like time_update_entry or time_delete_entry, and no prerequisites. The critical constraint that exactly one of issue_id or project_id must be supplied is only discoverable in the schema, not the description.

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 a non-destructive, idempotent mutation, and the description adds meaningful partial-update semantics ('only the fields passed change'). It does not disclose permission requirements, error behavior, or what happens to omitted fields beyond the partial-update implication.

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

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

A single front-loaded sentence with no wasted words, and the partial-update qualifier earns its place. It is efficient, though its terseness contributes to the gaps scored elsewhere.

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

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

For a five-parameter mutation tool with low schema description coverage and no output schema, the description is too thin. It omits parameter semantics for four fields and any usage context, leaving the agent under-informed despite the safety 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 20% (id is documented; hours, comments, spent_on, activity_id are not). The description does not compensate by explaining any of those four parameters, so an agent gets no added meaning for most inputs.

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 ('Updates a time entry'), which cleanly distinguishes it from sibling time_log (create) and time_delete_entry (delete). However, it does not explicitly name or differentiate from those siblings, so it stops short of a 5.

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

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

Provides no guidance on when to use this tool versus time_log or time_delete_entry, nor any prerequisites or exclusions. The only usage-adjacent statement is the partial-update note, which is behavioral rather than contextual.

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 what data can be returned (memberships, groups), but omits error behavior for unknown ids and any permission 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?

A single front-loaded sentence with no filler; the verb, cardinality and payload scope land 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?

There is no output schema, so the description carries the burden of describing the return value; it does so only at a high level ('one user ... with optional membership and group data') without shape or null/missing-user behavior. Adequate for a simple lookup but not thorough.

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

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

Schema description coverage is 100%, so the schema already documents both id (including the 'current' alias) and include. The description's mention of 'optional membership and group data' loosely restates include without adding format or value guidance, so baseline 3 applies.

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

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

States a specific verb and resource ('Returns one user by id') and the optional payload scope. This distinguishes it implicitly from users_list, but it never names or contrasts the closest sibling, users_get_current, which also returns a single user.

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

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

No when-to-use guidance at all. The agent must infer that 'by id' excludes the current-user case handled by users_get_current, and nothing explains when to pass include versus calling users_list instead.

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 the safety profile (readOnly, idempotent, non-destructive). The description adds genuine behavioral context: this performs a live lookup against /users/current.json rather than reading a cache, which matters for freshness and latency decisions.

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 with zero filler. The identity of the tool is front-loaded and the sibling comparison follows 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?

There is no output schema, yet the description enumerates the returned fields, so an agent knows exactly what it will receive. Combined with the live-vs-cached distinction, nothing needed to call or interpret this tool is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The listed fields describe the response, not inputs, so they add no parameter meaning but no gap either.

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 ('Returns the signed-in account') and names the concrete returned fields (id, login, name, mail, admin flag). It also differentiates itself from the sibling session_status by labeling itself the live check versus the cached copy.

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 clause 'The live identity check; session_status reports the cached copy' tells the agent which alternative to pick when freshness matters. It stops short of an explicit when-not rule (e.g., avoid on every call for performance), but the routing guidance is clear.

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

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

Annotations already state readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by explaining the 403 diagnostic semantics and what visibility information is included, though it does not elaborate further on response shape or 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?

The description is front-loaded with the core answer to 'what can I see' and follows with the operational 403 guidance. Both sentences earn their place, with no redundant restatement of annotations or schema details.

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

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

For a zero-parameter, read-only tool with annotations and an output schema, the description supplies the missing context: what visibility data is returned and how to use it diagnostically before related queries. Nothing essential for correct invocation appears to be missing.

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

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

The tool has zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly does not waste space describing inputs, as there are none.

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?

It concretely states what the tool exposes: admin flag, group memberships, and every visible project with roles. It also distinguishes this visibility/access tool from querying issues or users outside the caller's projects, so an agent can tell why this tool exists.

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 timing and diagnostic guidance: use it before querying issues or users outside your projects, and interpret a 403 as an object outside the visible scope rather than malformed input. This is actionable when-to-use guidance, not just a restatement of the tool name.

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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds the self-scoping constraint and the mutable fields, but omits key behavioral details: all three params are optional (partial update), how uniqueness/validation of mail is handled, and the response behavior.

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

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

A single front-loaded sentence with no filler or repetition. Efficient, though the extreme terseness leaves valuable space unused for a mutation 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?

For a mutation tool with 0% parameter documentation, no output schema, and all-optional params, the description is too thin. It never states that a partial update is possible, what happens on invalid mail, or what the call returns, so an agent cannot invoke it confidently.

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 names mail and 'name' (covering firstname/lastname) but does not explain the split between first and last name, optionality, formats, uniqueness constraints, or the minLength:1 requirement. 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?

Clear verb+resource: 'Updates the signed-in account name or mail address.' The 'signed-in' scoping distinguishes it from sibling reads like users_get_current and users_list, though it doesn't explicitly name an alternative writer. The field list maps to firstname/lastname/mail in the schema.

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

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

Usage is only implied by the 'signed-in account' scoping and the update verb. There is no explicit when-to-use, no prerequisites (e.g. must be authenticated), and no pointer to alternatives for editing other users. Minimum viable, not more.

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 destructiveHint=true, so the safety profile is partly covered. The description adds a meaningful extra fact beyond that: the deletion is irreversible ('This cannot be undone'), which is not conveyed by destructiveHint alone.

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 with the core action first and the critical warning immediately after; nothing is padded or repeated. 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 simple two-parameter delete with full schema coverage, complete annotations, and no output schema, the description covers purpose and irreversibility adequately. It stops short of noting permission requirements or side effects on related pages, which would make it fully complete.

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

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

Schema description coverage is 100% with only two parameters, both of which are documented in the schema as 'Project id or identifier' and 'Page title.' The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Deletes a wiki page'), which cleanly separates it from siblings like wiki_save_page, wiki_get_page, and wiki_list_pages. An agent can identify the operation without opening the schema.

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

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

There is no guidance on when to choose this over alternatives (e.g., overwriting via wiki_save_page) or on prerequisites such as the page or project needing to exist. The irreversibility warning is a caution, not usage routing, so the agent gets no when/when-not context.

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 that the response includes text and attachments, which is useful, but says nothing about error behavior for missing pages or the significance of fetching an old version.

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

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

A single front-loaded sentence with no filler. It is appropriately sized, though it is thin enough that a little more substance could have been added without bloat.

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

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

For a simple read tool with full annotation coverage, a fully documented 3-parameter schema, and no output schema, the description adequately signals the return content (text and attachments). Only minor behavioral detail is missing, which is acceptable here.

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

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

Schema description coverage is 100%, so title, project_id, and version are already documented in the schema. The description adds no further parameter meaning (e.g., version semantics or identifier formats), so the baseline of 3 applies.

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

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

The description uses a specific verb ('Returns') and resource ('one wiki page') and states the payload ('text and attachments'). It is clear what the tool does, though it does not explicitly name how it differs from siblings like wiki_list_pages or wiki_save_page.

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

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

There is no guidance on when to use this tool versus wiki_list_pages (browsing) or wiki_save_page. No prerequisites, no conditions, no alternatives are mentioned, leaving routing to the agent's 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds only the scoping fact that the index belongs to one project; it says nothing about pagination, result ordering, or whether page content is included. With annotations carrying the safety burden, this is an adequate but thin contribution.

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

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

A single front-loaded sentence with zero filler, so nothing is wasted. It is not structured beyond that one clause, but there is no bloat to trim.

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 simple (one fully documented required param, safety covered by annotations, no output schema), so a brief description is defensible. However, for a list endpoint it omits pagination behavior and what the returned index actually contains, which an agent may need before calling.

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

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

There is a single parameter (project_id) with 100% schema description coverage, so the baseline is 3. The description notes the list is scoped to a project, which loosely maps to project_id but adds no format or identifier semantics beyond the schema's 'Project id or identifier.'

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 (Lists) and resource (wiki page index) scoped to a project, which implicitly distinguishes it from the wiki_get_page/wiki_save_page/wiki_delete_page siblings. It never names those siblings or explicitly contrasts index listing with page retrieval, so it stops short of full differentiation.

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

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

No statement of when to use this versus wiki_get_page, search_query, or files_list_documents. The scope word 'of a project' implies you need a project context, but there is no explicit when/when-not guidance or prerequisites.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully corroborates the upsert/versioning behavior ('saves a new version'), implying history is preserved rather than overwritten, but adds nothing about authorization, rate limits, or what a successful call returns.

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 well-formed sentence with the conditional logic front-loaded and zero filler. It is efficient, though extremely terse for a mutating tool, leaving little room for the routing and constraint information an agent would benefit from.

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 four-parameter upsert with no output schema, the description is minimally adequate: annotations cover safety and the schema covers all parameters. However, it omits permission requirements, concurrency/version-conflict behavior, and the fact that a write is happening in a specific project context, which leaves real gaps for an agent acting without other 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 description coverage is 100% — title, text, comments, and project_id are all documented in the schema, including that text defaults to Textile and comments is a version comment. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb pair and resource ('Creates the page... otherwise saves a new version'), making the upsert semantics explicit and distinguishing it from read-only siblings like wiki_get_page and wiki_list_pages. It does not name those siblings explicitly, so it stops short of a 5.

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

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

There is no when-to-use guidance, no mention of alternatives (wiki_get_page, wiki_delete_page), and no prerequisites such as required project permissions or whether the project must already exist. The only usage signal is the implied create-vs-update behavior.

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