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

No annotations are provided, so the description carries the full behavioral burden, yet it never says this creates an immutable comment (append-only mutation), what it returns, or whether commenting on closed issues fails. The only disclosed trait is that body content is interpreted as markdown, which is thin for an unannotated write 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?

One short, front-loaded sentence with zero redundancy or filler. It is efficient, though its brevity is partly under-specification rather than disciplined concision.

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

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

For an unannotated mutation tool with no output schema and one undocumented third parameter, the definition omits return shape, failure conditions, and permission requirements. An agent could invoke it but could not predict outcomes or handle errors from the description alone.

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 67% and the two documented parameters ('Issue key or URL', 'Site name or host') are already explained in the schema. The description's only added meaning is that the 'markdown' parameter is a markdown-formatted body, a marginal but real clarification beyond the bare string type.

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

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

The description states a specific verb and resource ('Comment on an issue') plus the content format ('markdown'), which is enough to separate it from page_comment and read tools like issue_get. It does not explicitly name the sibling it contrasts with, 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?

There is no guidance on when to use this versus page_comment, issue_update, or issue_transition, and no prerequisites such as required permissions or issue state. The agent must infer the choice from the resource noun 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?

No annotations are supplied, so the description bears the full behavioral burden for a write operation. It does not state permission requirements, whether creation is idempotent, what happens on duplicate issues, or what the response contains. The only behavioral hint is the cryptic note that fields map names or ids to plain values.

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 single sentence is front-loaded and free of waste, but for an 8-parameter create tool it is terse to the point of under-specification. Efficiency is good; sufficiency is not.

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

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

For a mutation tool with no annotations, no output schema, 8 parameters (two required), and a nested object, the description omits required-field guidance, site/project defaults, return value, and failure behavior. An agent could not call this confidently without reading the schema closely.

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 63%, and the description adds real meaning only for the nested `fields` object, explaining that keys may be names or ids and values are plain. Other params (labels, summary) remain undocumented in both schema and description, so it partially compensates but leaves gaps.

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

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

The description opens with a specific verb and resource: "Create an issue." That clearly separates it from issue_get, issue_update, issue_delete, and issue_transition. It does not explicitly name or contrast with any 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?

There is no guidance on when to use this versus issue_update or issue_transition, no prerequisites (site, project, permissions), and no note about required type/summary. The agent must infer all usage conditions from 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 declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered by structured data. The description still adds genuine value by stating the deletion is permanent and by disclosing the subtask rule, which tells the agent an extra flag may be required to succeed. It does not say what happens if the flag is omitted on a parent issue, which keeps it at 4.

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 filler, with the destructive nature front-loaded before the conditional subtask detail. Nothing here could be removed 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 three-parameter delete tool with destructiveness already covered by annotations and full schema coverage, the description supplies the two things an agent most needs: irreversibility and the subtask flag requirement. It omits permission requirements and the failure mode when a parent issue is deleted without the flag, which is a modest gap given the tool's simplicity.

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 key, site, and deleteSubtasks are all documented in the schema, which sets the baseline at 3. The description's 'Subtasks require deleteSubtasks: true' slightly strengthens the meaning of that flag beyond the schema's 'Also delete subtasks; default false', but it does not explain key formats (ID vs URL) or site semantics.

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

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

The description opens with a specific verb and resource: 'Permanently delete a Jira issue.' That cleanly separates it from issue_update, issue_transition, and page_delete, which all operate on different resources or with different intent. It stops short of explicitly naming a sibling, so it lands at 4 rather than 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 destructive 'permanently delete' framing, and the sentence about subtasks functions as a precondition for calling it. However there is no explicit when-to-use guidance against alternatives such as issue_transition (e.g. closing vs deleting) and no warning to confirm intent before an irreversible 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?

With no annotations, the description carries the full burden; it does signal a non-mutating read and discloses the return shape ('markdown'), which is real value. However, it says nothing about permissions, error behavior for missing issues, or that comments are omitted unless requested, leaving meaningful gaps for a tool with no annotation coverage.

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, front-loaded with the action and resource, with zero filler. It is arguably too terse rather than too verbose, so it does not reach 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?

There are four parameters, no annotations, and no output schema, yet the description is one sentence. It fails to explain comment inclusion, site selection, or the response structure, which is inadequate for a fetch tool whose contract is otherwise undocumented.

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 75%, so the baseline is 3, and the description adds little beyond it: 'key fields' loosely gestures at the default field set relevant to the 'fields' parameter, but 'site' and 'include_comments' get no explanation anywhere. The undocumented include_comments parameter is the most notable miss.

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

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

Specific verb plus resource ('Read a Jira issue') and it states what comes back ('key fields and description as markdown'), so it is clearly distinguishable from issue_search or issue_update. It does not explicitly name a sibling to route against, which keeps it below a 5.

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

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

Usage is only implied: 'Read a Jira issue' suggests fetching a single known issue, and the required 'key' parameter reinforces that. There is no explicit statement of when to prefer this over issue_search or issue_comment, and no mention of prerequisites such as site access.

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?

Since no annotations are provided, the description offers minimal behavioral context. It only discusses input modalities and does not mention limitations, rate limits, or specific error handling behavior.

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

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

The description is highly concise, delivering all necessary core information in a single, direct sentence without any filler.

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

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

The tool explains what it searches and how it searches. However, as a search endpoint, it lacks completeness regarding result structure, pagination behavior, or potential result volume limitations beyond the basic schema coverage.

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

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

The description significantly aids the agent by explaining how the ambiguous 'query' parameter should be formatted. This semantic guidance is highly valuable, especially since the schema provides no description for this specific required input.

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

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

The description clearly identifies the tool's action (Search), the resource (issues), and the method (JQL or plain text). This specificity is highly effective for an agent.

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

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

It provides clear guidance on the input format by distinguishing between JQL and plain text search terms. While it doesn't explicitly name sibling tools to avoid (like issue_get), the action-verb distinction makes its purpose 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?

With no annotations supplied, the description carries the full disclosure burden, yet it says nothing about whether this is a mutating operation, whether it requires specific permissions, whether invalid statuses or disallowed transitions cause an error, or what side effects (comments, notifications) occur. Only the bare mutation is implied.

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 single short sentence is front-loaded and free of waste, but it is under-specified rather than concise; there is no structure beyond the one clause to guide the agent.

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 zero annotations, no output schema, and a close sibling in issue_update, the description leaves too much unsaid: no failure modes, no permission model, no distinction from siblings. It is only minimally adequate given the tool's complexity.

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

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

Schema description coverage is 100% and each of the three parameters (to, key, site) is documented in the schema itself, so the baseline of 3 applies. The description adds no meaning beyond that — notably it does not clarify whether "to" accepts a status name, a transition name, or an ID.

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 pairs a verb ("Move") with a resource ("an issue") and states the target concept (a status), so the basic intent is legible. But it never distinguishes this from sibling tools like issue_update or issue_create, and "move" is ambiguous for what is really a workflow status transition, so an agent cannot tell from the text alone which sibling to pick.

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

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

No guidance is given on when to use this instead of issue_update, nor on prerequisites such as whether the target status must be reachable via an allowed workflow transition. The agent must infer all usage conditions from the 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?

No annotations are provided, so the description must carry the full behavioral burden. It implies a mutation but does not disclose permissions required, whether updates are partial or full replacements, how the nested fields object is handled, or what happens to unspecified 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?

The description is a single efficient sentence with no wasted wording. However, its brevity contributes to under-specification rather than precision, which is better assessed under contextual completeness.

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

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

For a mutation tool with no annotations, no output schema, five parameters, and a nested fields object, the description is too thin. It does not explain partial update semantics, field value formats, permissions, or how the site parameter affects the operation.

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

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

Schema description coverage is 80%, so the schema already documents most parameters, including key, site, fields, and description as Markdown. The description adds little beyond naming the updatable areas, and it does not clarify the fields object structure or how summary and description interact with fields.

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: update an issue's fields, summary, or description. It is clear what the tool does, but it does not distinguish itself from sibling tools like issue_transition or issue_comment, which also modify issue-related data.

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 alternatives such as issue_transition, issue_comment, or page_update. It also omits prerequisites or conditions, leaving the agent to 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?

No annotations are supplied, so the description carries the full burden. It does not say whether the page must already exist, what permissions are needed, whether the append is atomic, how the markdown is inserted relative to the last block, or what is returned.

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 efficient, though its brevity comes partly at the cost of the behavioral detail the tool lacks 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?

This is an unannotated mutation tool with no output schema and one undocumented parameter. The description leaves out prerequisites, side effects, and return behavior, which is a significant gap for a write operation.

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

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

Schema coverage is 67%, with url and site documented but markdown left bare. The description only confirms that markdown is the content appended to the page identified by url; it adds no format, escaping, or size guidance beyond the schema.

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

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

The description gives a specific verb and resource ('Append markdown to the end of a page'), and the phrase 'to the end' distinguishes it at least implicitly from page_edit and page_update_section. It does not name any sibling 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 or when-not-to-use guidance and no mention of the obvious alternatives (page_edit, page_update_section, page_comment). The agent must infer from the name alone that this is the append-only variant.

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

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

No annotations are provided, so the description carries the full behavioral burden. It identifies the action as adding a footer comment but does not disclose permission requirements, whether the comment is immediately visible, idempotency, 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, front-loaded sentence with no wasted words. It is appropriately concise, though its brevity contributes to gaps in usage and parameter guidance.

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

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

For a mutation tool with no annotations and no output schema, the definition is under-specified. It lacks usage context, permission expectations, return behavior, and parameter guidance, leaving an agent with too little to 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?

The description adds no meaning beyond the input schema. Schema coverage is 67%, and the markdown parameter has no schema description at all, so the description should ideally clarify its expected format but does not.

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

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

States a specific verb and resource: "Add a footer comment to a page." This clearly distinguishes it from page-editing siblings and from issue_comment by resource, though it does not explicitly name alternatives.

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

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

Provides no when-to-use or when-not-to-use guidance. It does not mention prerequisites, whether the page must exist, or how this differs from page_append or issue_comment beyond the implicit "page" vs "issue" distinction.

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

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

No annotations are supplied, so the description carries the full disclosure burden for a mutation tool, and it says nothing about permissions or auth requirements, whether a duplicate title errors or overwrites, whether site/space defaults apply, or what the call returns. Only the input format (markdown) is disclosed. This is a substantial gap for a write 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?

A single front-loaded sentence with no filler or redundancy. The brevity is efficient, though it shades into under-specification rather than optimal conciseness.

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

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

For a five-parameter mutation tool with no annotations and no output schema, the definition leaves out return behavior, error cases, and placement semantics (site/space/parent interactions). An agent could not call this confidently without inspecting the schema and guessing at side effects.

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 60%: site, space, and parent are documented in the schema, while title and markdown are not, though both are self-evident and required. The description adds nothing about parameter behavior (e.g., what happens when parent is omitted or how space defaults from site), so the baseline 3 applies rather than a higher score.

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

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

The description gives a specific verb and resource ("Create a page") plus the input format (markdown), so the agent knows exactly what operation is performed. It does not distinguish this from close siblings such as page_append, page_edit, or page_update_section, which also write page content, so the sibling-differentiation bar for a 5 is not met.

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 indication of prerequisites, and no mention of the alternatives (page_append, page_edit, page_update_section) that an agent must choose between when adding content to a site. The agent must infer everything 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 flag destructiveHint=true and readOnlyHint=false, so the lower bar applies; the description still adds real value by clarifying this is a move-to-trash (soft delete) rather than a purge, and that drafts are unaffected. It stops short of saying whether child pages, attachments, or comments are affected and whether the action is reversible.

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 primary action and followed by the key scoping constraint; 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?

For a two-parameter destructive tool with annotations covering the safety profile and no output schema, the description supplies enough to call it correctly, though it omits side effects on page hierarchy/attachments and any permission requirements.

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% with both url and site documented, so the schema does the heavy lifting; the description only adds the qualifier that the target must be a published page, which mildly informs the url parameter but adds no format or identification guidance.

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 ('Move a published Confluence page to trash') and immediately scopes what it is not ('Does not purge pages or delete drafts'), so the agent can tell it apart from edit/create/append siblings and from any purge-like behavior.

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 sentence 'Does not purge pages or delete drafts' gives a clear exclusion and implies the tool applies only to already-published pages, but no sibling/alternative tool is named and no prerequisites (permissions, confirmation) are 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?

With no annotations, the description carries the full behavioral burden. It does disclose two genuinely useful facts — matching is exact/literal, and edits apply to raw storage XHTML rather than rendered text — but omits what happens when no match is found, whether the default replaces only the first occurrence, and whether the write is reversible or requires elevated permissions.

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, which is the right shape for a narrow tool. It is arguably under-specified rather than concise, but structurally it is clean.

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

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

For a five-parameter mutation tool with no annotations, no output schema, and 40% of parameters undocumented in the schema, this one-line description leaves too much unstated — match-failure behavior, idempotency, and scoping via url/site all go unexplained.

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 60%: 'all', 'url', and 'site' are documented, while the required 'find' and 'replace' have no schema descriptions. The description partially compensates by implying 'find' is an exact literal string, but adds nothing about 'replace' escaping or the first-match-only default when 'all' is false.

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 (find and replace) and a specific resource (the page storage XHTML), and the word 'exact' narrows it to literal matching rather than regex or fuzzy search. It does not, however, distinguish itself from close siblings such as page_update_section or page_append, which also mutate page content.

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

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

There is no guidance on when to choose this tool over page_update_section, page_append, or page_get. The only implicit signal is 'exact', which suggests targeted surgical edits rather than section rewrites, but the agent must infer that.

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

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

No annotations are supplied, so the description carries the full burden; it does disclose that three output encodings exist and characterizes the outline format. It is silent on permission requirements, behavior on very large pages, and what happens when id, url, and site disagree or are all omitted, which is a meaningful gap for a tool with 5 optional params.

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 that covers the verb, the resource, and the format dimension. It is efficient, though the terseness leaves gaps that a second sentence about id/url/site selection could have closed.

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

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

For a read-only tool with no output schema and a fully described schema, format enumeration plus the outline explanation is a reasonable core. It falls short on the optional id/url/site triple and the section parameter, which an agent needs resolved to invoke the tool 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 100%, so the parameters are already documented and the baseline is 3. The description does add a little meaning by naming the three format values and explaining that outline yields headings and tables, but it says nothing about id vs url vs site precedence or what section does.

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 ("Read a Confluence page") plus the three possible renderings, which separates it from mutating siblings like page_edit or page_update_section. It does not explicitly name any sibling, but the read-vs-write split 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 choose this over page_search, table_get, or the section-oriented page_update_section, and no prerequisites or exclusions. The only implied usage is the generic act of reading a page, which the agent would infer 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read-only search but does not describe authentication needs, pagination, result limits, 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?

The description is a single front-loaded sentence with no wasted wording. It is very terse, but that terseness reflects under-specification rather than verbosity.

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 search tool with no annotations and no output schema, the description is too sparse. It omits site/space scoping behavior, pagination, result format, and practical differences between CQL and plain text.

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 description adds meaningful semantics for the required 'query' parameter by indicating that it accepts CQL or plain text, which the schema does not explain. However, it does not clarify the 'space' parameter, and schema coverage for parameters is only 50%.

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: 'Search pages', and adds that the query can be CQL or plain text. It distinguishes itself implicitly from page_get, but it does not explicitly differentiate itself from sibling tools or clarify the scope of the search.

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 alternatives such as page_get or issue_search. It also does not state prerequisites, exclusions, or how to choose between CQL and plain text.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuinely useful trait - macro-preserving {{atlas:N}} tokens must be retained - but says nothing about reversibility, whether nested sub-sections are affected, or what happens if the heading is absent.

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 operation stated first and the critical caveat second; every clause earns its place and nothing is 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?

For a destructive write with zero annotations and no output schema, the definition covers the highest-risk failure mode (macro token destruction) but omits heading-not-found behavior, sub-section handling, and result confirmation. Adequate to call safely, not complete.

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

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

Schema coverage is only 50%, with 'heading' and 'markdown' undocumented in the schema; the description compensates by framing heading as the section anchor and markdown as the replacement format with token-preservation rules. It leaves the optional 'site' versus 'url' relationship unaddressed, which keeps it from a 5.

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

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

States a specific verb and targeted resource: 'Replace the content under a heading with markdown'. The section-scoped replacement is clearly a different operation from whole-page editing, though it never names page_edit or page_append 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?

Usage is only implied by the verb 'replace ... under a heading' - an agent can infer this is for swapping one section's body rather than appending or rewriting a whole page. There is no explicit when-to-use, when-not-to-use, or named alternative among page_edit/page_append.

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

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

With no annotations, the description carries the full burden, and it does hint that each entry includes reachability information rather than just names. However, it never states that this is a read-only, side-effect-free call, nor whether authentication is required or how large the result set can be.

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, and the object of the listing comes before the qualifier. It is on the terse side — 'what they can reach' is slightly ambiguous phrasing that a few more words could sharpen.

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 list tool with no output schema and no annotations, the description is roughly proportionate but leaves the return shape undefined: 'what they can reach' gestures at permissions or scopes without saying what fields come back. An agent knows what it gets in broad strokes but not how to interpret the response.

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 phrase 'configured sites' usefully implies the set is server-side configuration rather than a caller-supplied filter.

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

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

Uses a specific verb ('List') with a specific resource ('configured Atlassian sites') and adds scope ('what they can reach'). It is obviously distinct from the page_* and issue_* siblings, which operate on content rather than site configuration, though it never explicitly names that distinction.

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: nothing says whether this should be called first to discover sites before other operations, or that it takes no arguments and cannot filter. The agent must infer the discovery use case entirely from the verb and resource.

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

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

With no annotations provided, the description carries the full behavioral burden, and it does not disclose that this is a mutation, whether the target table must already exist, what happens with unknown column names, or whether the operation is idempotent. Only the word "Add" implies a write, leaving error and side-effect behavior unexplained.

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

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

A single compact sentence with the action front-loaded and no filler. It is efficient, though the terseness leaves little room for the context a mutation tool needs.

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

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

For a 5-parameter mutation tool with a nested object, no annotations, and no output schema, the description says too little: return value (e.g., row index or label), default placement behavior, and failure modes are all unaddressed. The agent has enough to guess an invocation but not enough to use it reliably.

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 already 80%, documenting url, site, table, and position, so the schema does most of the work. The description does add genuine meaning for the undocumented `cells` object by explaining that keys are column names and values are cell contents, which is not stated in the schema, but it adds nothing for the remaining 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?

States a specific verb and resource ("Add a table row") and clarifies the core payload semantics (cells map column names to values), which lets an agent distinguish it from table_get and table_update at a glance. It stops short of naming siblings or stating scope conditions, 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?

There is no guidance on when to use this versus table_update (e.g., creating a row vs modifying an existing one), no prerequisites such as the table needing to exist, and no mention of whether the row is appended by default. The agent must infer all usage conditions.

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

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

With no annotations, the description carries the full behavioral burden, yet it only discloses the output format (markdown). It says nothing about read-only semantics, authentication/scope needs, error behavior when the table isn't found, or size/pagination limits for large tables.

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 single sentence is front-loaded with zero filler, which is good, but at six words it is undersized for a tool with three parameters and no annotations, and the phrase "one page table" is awkward and easy to misparse.

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

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

Given no annotations, no output schema, and three parameters, the description is too thin to fully inform an agent about scoping, table selection, or failure modes. Only the return format is covered.

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 explains url, site, and that table accepts an index or heading. The description adds no extra meaning to those parameters; the baseline 3 applies since the schema does the work.

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

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

"Read one page table as markdown" gives a specific verb (read), resource (a table on a page), and return format (markdown), which distinguishes it from the mutation siblings table_update and table_add_row. It doesn't explicitly contrast with page_get or clarify whether "one page table" means a single table per page, leaving some 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?

There is no when-to-use or when-not-to-use guidance and no named alternative. An agent must infer on its own that this is for extracting tabular data from a page rather than fetching the whole page with page_get.

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

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

No annotations are supplied, so the description bears the full burden of behavioral disclosure. It does not say whether an existing cell value is overwritten, whether a missing row label or column header causes an error or creates one, what permissions are needed, or what the response contains — significant omissions 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 eleven-word sentence with the action and addressing scheme front-loaded and no filler. It is efficient, though the extreme brevity borders on under-specification rather than pure conciseness.

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

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

With six parameters, a mutating effect, no annotations, and no output schema, the description is too thin — it omits overwrite semantics, error/creation behavior for unmatched row or column, and how table selection interacts with url and site.

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%: url, site, and table are described in the schema, while row, column, and value are bare strings. The phrase "matched by row label and column header" usefully clarifies that row and column are lookup keys rather than indices, partially compensating for the gap, but the relationship between url/site/table is still left implicit.

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

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

The description gives a specific verb ("Set") and a precisely scoped resource ("one table cell"), plus the addressing mechanism (row label + column header). This implicitly separates it from table_get and table_add_row without naming them, so it is clear but not explicitly 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?

There is no guidance on when to prefer this over table_add_row or table_get, and no stated preconditions (e.g., whether the table must already exist or where the page/table identifiers come from). Usage is only inferable from the verb.

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