Verified Handles

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

Adds traits the annotations don't: 'staff-only' discloses visibility scope, 'Audited' discloses that the action is logged, and 'Dry run by default' warns that the call previews rather than writes unless overridden. This is meaningful context for a non-readOnly, non-idempotent mutation, though it omits who is authorized and whether repeated identical adds create duplicates.

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 compact fragments, purpose front-loaded, no filler. Each clause ('staff-only', 'links are kept', 'Audited', 'Dry run by default') carries a distinct piece of 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 an output schema present, return values need not be described, and the identifier semantics for entry are covered in-schema. The description covers visibility, audit, and the dry-run gate, leaving only minor gaps around authorization and duplicate-note 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 coverage is 67%: entry and dry_run are documented in-schema, while text is not. The description partially compensates by specifying that text is 'plain text' and that 'links are kept', which is real semantic value the schema lacks, but it says nothing about length limits or content restrictions.

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 ('Add a ... note to an entry') and qualifies the note as 'staff-only internal', which sets it apart from public comments like comment_on_application. It doesn't explicitly differentiate from edit_entry_note or delete_entry_note, but the verb choice makes the distinction inferable.

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 tool versus edit_entry_note, delete_entry_note, or list_entry_notes, and no prerequisites or exclusions. The only usage signal is the default dry_run behavior, which is implied rather than explained as a workflow step.

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

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

Annotations already flag this as destructive, non-idempotent and mutating, and the description goes well beyond them: it discloses that a live entry is created, the applicant is emailed, the assessment is overwritten with the given fields, the action is audited, and the dry run surfaces policy shortfalls and Wikidata-item conflicts.

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?

Front-loaded with the action and its effects, and every sentence carries information — side effects, warning behavior, the self-approval restriction, auditability, default mode. It is dense and slightly packed but has 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 destructive, multi-effect approval tool with an output schema and fully documented parameters, the description covers side effects, preconditions, the self-approval restriction, and the safe default. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top, explaining that dry_run defaults to true and only warns, and that assessment fields are applied as changes to the current assessment rather than supplied wholesale.

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 (approve an application) and enumerates the concrete consequences: the entry goes live from its proposal, the assessment is recorded alongside it, and the applicant is emailed. This clearly separates it from siblings like reject_application or assess_application without opening a schema.

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

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

Gives an explicit exclusion — never approve your own application unless you could create that entry directly — plus the default dry-run posture and the conditions the dry run warns about. It stops short of naming an alternative tool, but the when/when-not conditions are 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 declare non-readOnly, non-destructive, non-idempotent, but the description adds the real behavioral payload: the question is posted to the thread, the applicant is emailed, the application enters a waiting (needs_info) state until reply, and the action is audited. That is exactly the beyond-annotations context an agent needs.

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

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

Three tight sentences with no filler; the core action and its consequences are front-loaded, with the precondition, audit note, and dry-run default following compactly.

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, a 100%-covered input schema, and full annotations, the description supplies everything else an agent needs — purpose, side effects, precondition, audit, and default dry-run behavior — leaving no critical 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 description coverage is 100%, so parameters are already documented, and dry_run's default and message's limit are fully covered. The description clarifies the effect of the message (thread + email) but adds little parameter-level detail beyond what the schema states, matching the baseline.

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

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

States a specific verb (ask), resource (applicant), and the concrete effects — thread post, email, and transition to needs_info. These side effects clearly distinguish it from a plain comment_on_application, letting an agent pick the right tool without opening schemas.

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

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

'Only for an application waiting on a reviewer' is an explicit precondition that tells the agent when the tool applies. It stops short of naming alternatives (e.g., comment_on_application for non-blocking messages), so it lands just below the top band.

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 the mutation profile (readOnly=false, destructive=true, idempotent=false), so the safety bar is partly covered. The description adds genuinely new behavior: partial-merge semantics ('give only the fields that change; the rest stay as the application has them'), auditing, and the score preview from dry run.

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

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

Three tight clauses with no filler: partial-update rule, dry-run preview, audit note. Front-loaded with the core action and the critical 'without deciding it' qualifier.

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 8-parameter scoring mutation with an output schema, the description covers everything the agent needs: what it writes, the no-decision constraint, merge semantics, dry-run default, and auditability. Return values are legitimately covered by the output schema.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds a semantic the schema does not: unspecified fields are preserved rather than cleared. That merge behavior materially affects how an agent should populate the 8 parameters, so it earns above 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 — 'Save your assessment of an open application against the eligibility policy' — and immediately scopes it as 'without deciding it.' That clause cleanly separates it from the decision siblings (approve_application, reject_application, mark_application_spam) without needing to open either schema.

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

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

Gives clear usage context: it applies to 'an open application' and is explicitly not the deciding action, and it notes the default dry-run posture. It never names an alternative tool explicitly (e.g. 'to decide, use approve_application'), so routing is inferred 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?

Adds traits beyond the annotations: the comment is visible to the applicant, does NOT trigger an email, the action is audited, and it runs as a dry run by default. These are concrete, consequential behaviors (safety-by-default, audit trail, notification semantics) not derivable from readOnlyHint/destructiveHint/idempotentHint 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?

Three tight sentences, front-loaded with the action and its visible effect, then the alternative, then the audit/dry-run notes. 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 annotations, a 100%-covered schema, and an output schema present, the description supplies exactly the missing context (visibility, notification, audit, dry-run default) an agent needs to call it correctly. Nothing material is omitted.

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 body, dry_run, and application_id are already fully documented (including the dry_run default and body length limits). The description only restates the 'applicant sees it' semantics already present in the schema, 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 (add a message) and resource (an application's thread) and immediately defines the scope ('applicant sees it on their application'). It names the sibling ask_applicant and distinguishes itself from it, so an agent can route without opening a schema.

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

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

Explicitly gives the when-not/alternative: 'To ask them something and wait for the answer, use ask_applicant.' The condition that selects the alternative is stated, leaving nothing to inference.

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

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

Beyond the annotations (readOnlyHint=false, idempotent=false, dry-run not declared there), the description adds real behavioral context: the comment is 'Audited', it is 'Dry run by default', both reviewer and submitter see it, and answering a reviewer's question routes the application back to them — a non-obvious side effect an agent must know. This meaningfully exceeds what the structured fields 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?

The content is front-loaded: purpose first, then the reviewer/submitter visibility nuance, then the two terse operational flags ('Audited. Dry run by default.'). The parenthetical audience clause is dense but earns its place; 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?

An output schema exists, so return values need no explanation, and the description covers the important operational facts (auditing, dry-run default, visibility, workflow routing). The only remaining gap is that it doesn't explicitly contrast with the near-identical comment_on_application sibling, which an agent choosing between them would benefit from.

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 both required parameters (id, text) and dry_run are fully documented in the schema itself, including formats and limits. The description adds only the audience framing around 'id' and repeats the dry-run default, so it does not go meaningfully 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?

The description states a specific verb and resource — adding a message to a submission — and immediately scopes it by audience ('this key's own account's submissions', or 'any they may see' for a reviewer). That audience split is what separates it from the sibling comment_on_application, so an agent can distinguish the two without opening a schema.

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

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

It gives clear context for when this tool applies (commenting on your own submission, or a reviewer commenting on something visible) and notes the concrete case of answering a reviewer's question. It stops short of naming the alternative sibling (comment_on_application) or stating explicit exclusions, so it is clear-but-not-routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the note's content is retained in the audit log (so the deletion is discarding visibility, not history) and the operation is permission-gated to the author or entry managers.

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 compact sentences, front-loaded with the action and followed by the constraint and the default. 'Dry run by default' mildly duplicates the schema default, but as a headline safety cue it earns its place.

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

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

An output schema exists, so return-value explanation is not needed. The description covers the key things an agent needs: permission scope, audit-log retention, and the dry-run default. It stops short of describing failure modes (e.g., invalid note_id) but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 67%: 'entry' is richly documented in the schema (VHID/short name/QID) and 'dry_run' explains both branches. The description adds no parameter detail of its own beyond restating the dry-run default, and note_id carries only a regex pattern with no prose anywhere. Baseline 3 is appropriate.

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

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

States a specific verb ('delete') and resource ('an internal note on an entry'), which cleanly separates it from add_entry_note, edit_entry_note, and list_entry_notes. It even adds scope qualifiers (author or entry managers), so 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?

The permission parenthetical ('its author, or anyone who manages entries') tells the agent who is eligible, and 'dry run by default' hints at the safe call pattern. However, there is no explicit guidance on when to delete versus edit_entry_note, nor any stated precondition or when-not-to-use condition.

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=false, but the description adds substantial context beyond them: dry run is the default and never writes, content passes through an allowlist sanitizer, nothing is public until published, and calls are audited. This is exactly the extra behavioral detail annotations cannot 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?

Front-loads the core action and the dry-run default, and every sentence carries information. It is dense and reads as one long block, which makes scanning the parameter guidance harder than a short bulleted structure would, but there is little wasted text.

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

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

With an output schema present, the description does not need to explain return values, yet it still usefully describes what a dry run surfaces (cleaned HTML, slug, address, links, dropped tags/attributes). For a 14-parameter mutation tool with a default dry run, this is close to complete; only failure/validation behavior is left vague.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: slug is derived from title when omitted, about vs mentions distinction (mentions appear under 'In the news'), hero_media_id refers to an uploaded image, and hero_alt accompanies it. It does not enumerate all 14 params, but the gaps are ones the schema already covers well.

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 — 'Start a new article as a draft' — plus how it relates to Console → Articles and the publish step. Combined with 'nothing is public until a publisher publishes it', an agent can distinguish this from update_article_draft or get_article without opening a schema.

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

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

Implicitly scopes usage to creating new drafts and explains the dry-run-first workflow explicitly. It does not name update_article_draft as the alternative for editing an existing draft, so the create-vs-update boundary is left partly to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds real context beyond them: the author-only permission rule, an audit trail, and the dry-run-default behavior. It does not explain what happens to the prior note text or whether history is retained, which is the main residual gap for a destructive edit.

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 terse clauses, front-loaded with the action and followed by the two facts an agent most needs before calling. No filler and nothing buried.

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

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

An output schema exists, so return values need no explanation, and the description covers auth, audit, and dry-run for this mutation. The missing pieces are note_id provenance and whether the overwritten text is recoverable, which matter for a destructive rewrite.

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%: entry and dry_run are documented inline, while text and note_id have no descriptions anywhere. The description reinforces the dry-run default but does not explain note_id's format or where to obtain it (e.g., list_entry_notes), 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 ("Rewrite ... internal notes on an entry") and scopes it with "one of your own," which separates it from add_entry_note, delete_entry_note, and list_entry_notes without ambiguity. It stops short of naming a sibling explicitly, so it is clear but not maximally 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?

"only its author may" gives a hard precondition and "Dry run by default" tells the agent the safe calling pattern. It never states when to pick this over add_entry_note or delete_entry_note, but the rewrite semantics imply the context well enough.

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 only declare readOnlyHint and openWorldHint=false, but the description adds real behavioral context: an empty list is returned when nothing matches, case is ignored where the platform ignores it, and emails are excluded. This goes meaningfully beyond what the annotations 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?

The purpose is front-loaded as the quoted question, followed by input forms then output behavior. It is a single dense block with no wasted sentences, though the packing of output fields, case rules and the email caveat into one paragraph makes it slightly heavy to scan.

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, the description needn't restate return values, yet the tool is a simple read lookup whose annotations and schema cover safety and inputs well. The only meaningful gap is any statement of when this should be chosen over the other entry-retrieval siblings.

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 100%, so the baseline is 3. The description adds the mutual-exclusivity relationship the schema does not express ('url ... instead of platform and value') and gives concrete value formats (someone or @someone), which helps the agent pick a valid input shape.

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 (find entries by handle) and frames it as a reverse lookup, quoting the exact question it answers ('is x.com/someone an official account, and whose?'). This clearly separates it from siblings like get_entries and search_entries, which are not handle-keyed lookups.

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

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

Explains the two input ways ('Give a profile's address as url... or platform... and value') and gives an explicit exclusion ('Email addresses are not looked up'). It does not name a competing sibling tool or state when to prefer this over search_entries, so it stops short of full when/when-not routing.

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

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

Beyond the readOnlyHint, the description discloses genuinely non-obvious traits: the two body representations, the exact form of entry links in Markdown, the meaning of markdown_round_trips as a fidelity guarantee with a concrete failure mode (table spans, image sizes), and that the returned content reflects pending revisions rather than published state. That is substantive context an agent could not get from annotations or schema.

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

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

The first sentence is an extremely long run-on that enumerates fields inside nested parentheticals, which makes it hard to parse despite containing useful facts. The content largely earns its place, but the structure delays the core action behind a wall of field enumeration rather than front-loading what the tool does.

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

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

With an output schema present and annotations covering the read-only profile, the description is more than complete enough for an agent to call this correctly. Minor gap: it never clarifies the relationship to get_article_history or get_entry, which matters in a namespace this crowded.

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

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

Schema coverage is 100% and the schema already documents that the single `article` parameter accepts an id, an address, or a slug. The description adds nothing about that parameter — no format examples, no fallback behavior on ambiguity. Baseline 3 applies because the schema carries the full burden.

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 makes clear this returns a single article with its fields, byline, related entries, and both HTML and Markdown bodies. That level of specificity on returned content distinguishes it from list-oriented siblings like list_articles, though it never states the verb explicitly or names adjacent readers like get_entry or get_article_history.

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 — the reader must infer that this is the tool for fetching one article's current content. There is no explicit when-to-use, no exclusions, and no routing to alternatives such as get_article_history for past versions or list_articles for discovery. The one piece of actionable guidance ('edit in HTML' when markdown_round_trips is false) is about editing, not about selecting this tool.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description adds substantial behavioral detail beyond that: newest-first ordering, a 50-item limit, exact event types included, the metadata returned for each event, and the distinction between current_revision and pending_revision. There is no contradiction with 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?

The definition is only two sentences and is front-loaded with the core return behavior. The dense first sentence earns its length by enumerating event types and returned metadata, while the second sentence cleanly explains current_revision and pending_revision.

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

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

Given the tool’s simplicity, full schema coverage, annotations, and an available output schema, the description is complete enough for correct invocation. It covers ordering, result limit, event scope, returned fields, and the special meaning of current_revision and pending_revision.

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

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

The single article parameter has 100% schema description coverage, including accepted forms such as id, address, URL, or slug. The description does not add any parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states exactly what the tool returns: an article’s revisions, newest first, limited to the last 50, with enumerated event types such as saves, publications, schedules, slug changes, and takedowns. This is specific enough to distinguish it from get_article and get_entry_history, which cover current article data and entry history respectively.

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

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

The description implies this is the tool for viewing an article’s revision history and clarifies the meaning of current_revision versus pending_revision. However, it does not explicitly say when to use this tool instead of get_article or get_entry_history, nor does it name exclusions 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 cover the read-only, closed-world safety profile, and the description still layers on useful behavior: results come back in the order given, each item resolves to an entry or not_found, and the view is the signed-out one. Partial-failure semantics (per-item not_found rather than a whole-call error) are exactly the kind of detail an agent needs.

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 dense sentence with the batch size and identifier constraint front-loaded and no filler. The nested parenthetical and em-dash clause make it slightly harder to parse than it needs to be, but nothing 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?

Output schema exists so return values need no explanation, and annotations carry the safety profile. What remains — ordering, per-item failure mode, dedupe, QID exclusion — is all present, so an agent has everything needed to call this correctly on the first try.

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?

Adds meaning beyond the 100%-covered schema: the acceptable identifier forms are VHID or short name but explicitly NOT a Wikidata QID, and duplicate names collapse to one answer. That QID exclusion and dedupe rule are not in the schema and materially affect how the argument should be built.

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 (returns public records), the resource (entries), and the batch bound (up to 50 in one call), then explicitly differentiates itself from get_entry and search_entries. An agent can tell exactly what this does versus its siblings 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?

Explicitly excludes Wikidata QIDs and routes to get_entry or search_entries for item-based lookup, which is real routing guidance. It lacks a positive 'use this when batching many lookups to avoid N calls' framing, but the batch/inline-alternative split is otherwise 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context: the authentication gate ('Without an API key, the public record alone') and the exact contents of the editor payload, which go beyond what the annotations state.

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

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

The description is a single dense sentence that front-loads the core action and identifier formats, then explains the two response modes. Every clause carries information, though the nested 'as `editing` …' structure is slightly convoluted.

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

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

Given the presence of an output schema, complete parameter schemas, and annotations, the description is largely complete for an agent to invoke it correctly. It covers authentication behavior and the dual public/editing response shape, though it omits potential error conditions for invalid keys.

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 fully documented in the schema. The description restates the accepted identifier formats (VHID, short name, QID) and adds the API-key condition for platform data, but it does not add syntax or format details beyond what the schema already provides.

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

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

The description clearly states what the tool retrieves: one entry identified by VHID, short name, or QID, along with its public record and the editing payload. It implicitly distinguishes itself from the list-oriented sibling get_entries by emphasizing 'One entry,' but it does not explicitly name or contrast with 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?

Usage is implied by the singular 'One entry' and the note about what an editor would load, but there are no explicit when-to-use/when-not instructions or named alternatives such as get_entries or find_by_handle. The inclusion of the editing payload suggests an editing context, yet the description leaves the agent to infer selection criteria.

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

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

The annotations already declare this is a read-only, closed-world operation. The description adds useful behavioral context beyond annotations: the history is public, ordered newest first, paginated via next_offset, and merged entries expose their own history.

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 no wasted text. The core behavior is front-loaded and the edge case for merged entries is appended efficiently.

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

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

Given read-only annotations and an existing output schema, the description covers the key behavioral points an agent needs: public history, newest-first ordering, pagination, and merged-entry behavior. It is only slightly incomplete because it does not route the agent between this and related history/entry tools.

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

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

The entry parameter is well documented in the schema, but limit and offset have no schema descriptions and only 33% overall schema coverage. The description partially compensates by mentioning `next_offset` pagination, but it does not explain limit or offset semantics.

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

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

The description clearly identifies the resource as an entry’s public edit history, with sorting and pagination behavior. It does not explicitly distinguish this from siblings like get_entry or get_article_history, so it is clear but lacks sibling 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?

Usage is implied: call this to retrieve an entry’s edit history. The description does not explicitly say when to use this instead of get_entry or get_article_history, nor does it state exclusions or alternatives.

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

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

Annotations already cover read-only status, but the description adds genuinely new behavior: it 'Reads the item live through the sync's rate limit', explains `state: unknown` when Wikidata did not answer, and describes `propose: null` with `pending_id` while a change waits in Review. That is useful context beyond the annotations, though the write-side routing is buried in output prose.

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 purpose is front-loaded in the first clause, but the remainder is a single sprawling ~400-word block of nested parentheticals detailing return fields. Since an output schema already exists, this return-value exposition largely duplicates structured data and is not appropriately sized.

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 complex reconciliation read with a simple input schema and a present output schema, the description covers read semantics, rate limits, and the meaning of null/pending states and follow-up tools. It falls short only on explicit when-to-use guidance relative to sibling readers.

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 and schema description coverage is 100%, with the schema fully explaining VHID/short-name/QID forms. The description adds nothing about the `entry` argument, 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?

The opening sentence gives a specific verb+resource ('Console → Wikidata, per entry, as JSON: the entry against its Wikidata item, value by value'), which separates it from plain entry readers like get_entry or handle_health. It is clear what the tool is, but the phrasing is idiosyncratic and never states its name's scope plainly.

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: it says the field `propose` is 'the change propose_wikidata_changes could carry' and that removing a handle is done 'with update_entry_handles', which routes follow-up actions. However it never states when to call get_reconcile rather than get_entry or handle_health, nor any prerequisite.

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?

Beyond the annotations (destructive, idempotent, non-read-only), the description adds real context: links surface on entry pages under "In the news" once live, changes are audited with the key and tool, and the call is a dry run by default showing before and after. That is meaningful disclosure of side effects, though the mechanism of the dry-run preview output is only sketched.

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

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

Four dense sentences, front-loaded with the core action and default semantics before the dry-run note. Nothing is wasted, though the parenthetical clauses make it slightly harder to scan than it could be.

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 a full input schema and an output schema present, the description only needs to cover behavior, and it does: defaults, replace semantics, audit, and the dry-run preview. Only minor edge cases (e.g., an entry appearing in both `about` and `mentions`) go unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above that by explaining cross-parameter behavior — how `about`/`mentions` combine with `remove`, and what `replace` overrides — which the per-field schema text does not convey.

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: setting the entries an article is about and mentions. That scope makes it distinguishable from siblings such as update_entries or set_article_hero, though it never names an alternative 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?

It gives clear operating context: the default is additive with a `remove` list, and `replace: true` makes the given lists the whole truth. What's missing is an explicit statement of when to prefer this over sibling tools like update_entries.

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 and openWorldHint=false, but the description adds real behavior: 30 items per page, ordering (oldest first for review queues), the assessment fallback rule (reviewer's saved one, else what the applicant claims), and per-item flagging of whether this account may approve it. That permission-awareness and sort/fallback context go beyond the annotations, though pagination limits and total counts are not discussed.

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?

Core purpose is front-loaded, but the body is one sprawling compound sentence with nested parentheticals and semicolon-chained clauses, which is hard to parse. Much of the item-content enumeration duplicates what the output schema already provides.

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?

Covers all four parameters' modes, explains the two tab families and the application_id variant, notes permission awareness, and cross-references the deciding tool. With an output schema present, return-shape detail need not be in the description, and the remaining parameter space is adequately addressed.

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%, and the description fully compensates: it maps each `tab` enum value to a concrete meaning (open, needs_info, approved, rejected, spam, retracted, all, proposals) and explains the proposals/decided split. It also conveys page size ("30 a page") and the application_id single-record mode, adding meaning the bare enum and schema fields do 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?

Opens with a specific verb+resource: the applications queue for new entries (Console → Applications), and details exactly what each item contains (proposal, applicant's case, assessment, score, existing Wikidata entry, approval eligibility). It is clearly a listing tool for applications, distinguishable from entry-listing siblings such as get_entries or list_review_queue.

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

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

Explains when each `tab` mode applies ("open" to review, oldest first; "needs_info" awaiting the applicant; "proposals" for quick proposals with no eligibility case) and when to pass application_id. It also routes the agent to review_submission for deciding and names propose_new_entry as the source of proposals. It never explicitly excludes or contrasts with adjacent listing tools like list_review_queue or list_my_submissions.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: deleted articles are excluded, results are ordered by newest change, and modified_at is explicitly defined as reader-facing last update.

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?

Content is front-loaded with the resource and scope, and every clause carries information. It is a single dense run-on sentence, though, which makes the field enumeration harder to scan than it needs to be.

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 covers scope, ordering, and filter semantics adequately. Minor gap: no explicit note on pagination or result volume for a list that could be large.

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% and three of four params are enums the schema already documents. The description mainly restates the filterable fields; its only real addition is clarifying that an author entry matches articles whose byline names it, which is largely echoed in 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+resource (list the site's News articles and guides) and pins down scope: excludes deleted, ordered by newest change, and enumerates returned fields. It is clearly distinguishable from single-item siblings like get_article and get_article_history.

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 'every one but a deleted one' scoping and the filter list imply when to use it, but there is no explicit when-to-use guidance and no named alternative (e.g. get_article for a single article). The agent must infer the boundary from siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description is not carrying the safety burden. It still usefully adds that results are staff-only (an auth requirement), returned oldest-first (ordering), and annotated with per-key permitted actions — none of which the annotations 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?

A single dense sentence front-loads the resource and scope, then adds ordering and content detail with 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?

An output schema exists, so return shape need not be explained, and the description covers auth scope, ordering, and the per-note permission payload. It omits pagination/volume behavior for what could be a long note list, a minor 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 description coverage is 100%, and the single 'entry' parameter is fully documented in the schema (VHID, short name, or QID). The description adds no additional parameter meaning, 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 (list) and resource (staff-only internal notes on an entry), plus scope and ordering (oldest first). The 'list' framing clearly separates it from its write siblings add_entry_note, edit_entry_note, and delete_entry_note, though it never names 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?

The 'staff-only' qualifier implies a precondition for use, but there is no explicit when-to-use/when-not statement and no reference to alternatives such as get_entry_admin or the note mutation siblings. Usage context 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds non-annotated behavior: newest-first ordering, a fixed page size of 25, the per-row fields returned, and that a single-id fetch can surface submissions a reviewer may also see. No destructive, auth, or rate-limit caveats beyond that.

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?

Dense but front-loaded: the list behavior and ordering come first, then the filter and the single-id mode. Every clause carries information, though the appositive-heavy style makes it one long breathless run rather than cleanly separated sentences.

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?

Output schema exists, so return fields need not be spelled out, yet the description still names what each row carries. Pagination, ordering, and auth scope (this key's own account) are covered; only the exact semantics of the alternate `status: all` value and page-boundary behavior are left implicit.

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 33% (page and status are undocumented in the schema), but the description compensates: it explains `status: open` as the filter for pending items and states the 25-per-page size, effectively documenting page. It adds meaning to `id` as well (yours or any a reviewer may see, with comment thread).

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 (list this key's own submissions), enumerates the record types covered (proposed changes, new-entry proposals, claims, reports, applications), and scopes it to the key's own account, which cleanly separates it from list_review_queue and list_applications. An agent can identify it without opening the schema.

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

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

Gives clear context for how to steer the tool — `status: open` for the still-waiting ones, `id` to fetch a single submission with its comment thread — but never explicitly names an alternative sibling (e.g. list_review_queue) or states when not to use this tool. Clear context, no exclusions.

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 and openWorldHint=false, and the description adds real context beyond that: a hard 100-item cap, oldest-first ordering, and the fact that status switches to decided items while defaulting to pending. It does not discuss whether listing is paginated past 100 or what happens to excluded types, leaving a small 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?

Front-loaded with purpose, ordering, and limit in the first clause, then routing guidance. The parenthetical about new_entity is long but earns its place as a disambiguation; a few clauses are dense enough to require rereading.

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, the description needn't document return shapes, and it covers the main operational facts an agent needs: scope, ordering, cap, exclusion of new_entity, and the deciding tool. Only pagination behavior past the 100-item limit and the less common status values are left unstated.

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

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

Schema coverage is only 33% (only `entry` is documented), but the description compensates by describing the `kind` values (correction/claim/report) in prose and explaining that `status` surfaces decided submissions versus the default pending queue. It doesn't spell out the full status enum semantics (merged, superseded, retracted), so it improves on but doesn't fully close 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+resource (list submissions awaiting a reviewer) plus scope details: content types (correction, claim, report), ordering (oldest first), and cap (up to 100). It explicitly carves out new_entity proposals and points to list_applications instead, so the agent can distinguish it from siblings without reading schemas.

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

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

Gives explicit when-to-use (reviewer queue, optionally with status for decided ones), when-not-to-use (new-entry proposals belong in list_applications with tab "proposals"), and names the follow-up action (decide with review_submission). Narrowing options are also 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?

Goes well beyond the annotations: it states the side effect (declined), the absence of notification to the applicant, irreversibility ('Cannot be undone'), and audit logging, plus the dry-run/confirm safety protocol. These are the exact behaviors an agent must know before a destructive call and are not derivable from destructiveHint=true 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?

Three compact sentences with no filler, and the highest-stakes facts (decline, no notification, irreversible) are front-loaded before the dry-run mechanics.

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, idempotency-free mutation there is an output schema and full parameter coverage, so the description only had to cover consequences, reversibility, audit, and the confirm workflow — all of which are present.

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 already 100%, so the baseline is 3; the description earns an extra point by clarifying the default (dry run) and the exact expected value of confirm (the application's id), tightening what the schema expresses more abstractly as 'this change's exact target'.

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 ('mark an application as spam') and immediately discloses the concrete effect ('it is declined, and the applicant is not told'), which an agent can distinguish from approve_application or reject_application. It stops short of naming the alternative sibling (reject_application) or the boundary condition that would pick one over the other, so differentiation is inferable rather than explicit.

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

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

Gives a clear precondition ('an open application') and the operational procedure (dry run by default; the real run needs confirm set to the application's id), which is exactly the context needed to invoke it. It does not say when not to use it or point to reject_application as the non-spam alternative, so it falls short of full routing guidance.

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

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

Goes well beyond the annotations (which only say non-readonly, idempotent, non-destructive): it discloses that nothing changes until a person approves, that a reviewer with Manage entries is required to approve a qid link, that the operation is audited, and critically that it is 'dry run by default' and what the dry run returns. These are high-value behavioral facts not derivable from 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?

Front-loaded with the core propose-for-approval framing and the dry-run default; sentences are dense but purposeful. It is on the longer side for a one-paragraph description, though for a 26-parameter tool the length is largely earned.

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 26-parameter, 81%-covered mutation tool with an output schema, the description covers the highest-risk behaviors: approval gating, dry-run default, audit, and the qid/adopt interaction. It omits some parameters (gallery, idempotency, revision conflict) but those are documented in the schema, so the description is nearly complete for what an agent must understand 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?

The description adds real meaning beyond the 81%-covered schema: null clears a field, qid links/re-points/unlinks with adopt controlling managed fields and the server default on first link, and note is framed as the reviewer's rationale. Minor gaps: it doesn't mention idempotency_key, base_revision_id, gallery, or handle ordering, but the schema documents those and coverage is high.

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 (propose a change for a reviewer to decide) and immediately distinguishes itself from live editing: 'for any entry you may propose to, including ones you could edit live.' Combined with the title and the 'nothing changes until a person approves it' framing, an agent can tell this apart from update_entry_fields/update_entries 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?

It establishes when to use it ('including ones you could edit live', propose vs. direct edit) and the key precondition that a reviewer must approve. It does not explicitly name the live-edit siblings or explain when to choose propose_entry_changes (bulk) versus this tool, so it stops short of full when/when-not routing.

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

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

Goes well beyond the annotations: discloses that nothing changes until a person approves each proposal, that changes are audited under one batch id, that re-proposing an identical pending change answers the same proposal, the atomic all-or-nothing behavior, and that it is dry-run by default. These are the exact behavioral traits an agent needs and are not captured by the hint flags.

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?

Front-loads the core purpose ('Proposals for up to 25 entries in one request') and each following clause carries distinct information (approval gate, batch id, idempotency, atomic, dry run). The opening sentence is long and dense, but there is little redundancy overall.

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 complex batch, multi-parameter mutation tool with an existing output schema, the description covers the key facts an agent needs: the approval gate, per-entry vs atomic semantics, dry-run default, and idempotency. Return-value detail is correctly left to the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema itself documents entry, short, handles, base_revision_id, atomic, dry_run, and idempotency_key in detail. The description restates the atomic and dry-run semantics but adds no syntax or format beyond what the schema already provides.

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 with scope ('Proposals for up to 25 entries in one request') and explicitly distinguishes itself from the singular sibling by noting 'each as propose_entry_change files one.' An agent can immediately tell this is the bulk variant of propose_entry_change.

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?

Clearly frames the batch use case (up to 25 entries in one request) and names the singular alternative by reference, giving strong context for when to pick this tool. However, it never states an explicit 'use this instead when X' or an exclusion, leaving the routing to inference.

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

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

Adds substantial behavior beyond the annotations: the proposal carries only the diff, ownership (Wikidata vs site) is untouched, withdrawn images are omitted and named in the answer, an audit trail exists, and refusal semantics are spelled out. No contradiction with readOnlyHint=false / destructiveHint=false / idempotentHint=false.

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 core action and default dry-run are front-loaded, and nearly every clause carries information (ref_id format, refusal, audit, payload scope). It is dense to the point of being a wall of clauses, which slightly hurts scannability.

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 multi-step proposal tool with an output schema present, the description covers what the proposal contains, its refusal case, the note's purpose, and the dry-run default, so nothing critical is left for the agent to infer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint on the revision parameter (imported legacy revisions cannot be put back) and explains what the note is for and what dry_run does. That is meaningful semantics beyond the schema text.

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+resource+scope: propose reverting an entry to an earlier revision for a reviewer to decide. It also differentiates from siblings by naming get_entry_history for obtaining the ref_id and characterizing the payload as what propose_entry_change would send, separating it from the direct restore_entry_revision 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?

Gives clear triggering context (needs a reviewer, needs a ref_id from get_entry_history, refused with nothing_to_change when the entry already matches), and the dry-run-by-default note guides invocation. It stops short of an explicit when-not rule contrasting with the sibling restore_entry_revision, so it's strong but not fully exhaustive.

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 substantial behavior beyond the annotations: dry run by default, audited, warns when the item belongs to another entry, skips handles the entry already has, sources the description from Wikipedia, and contrasts sync-backed vs copied values. This is well above the bar set by readOnlyHint=false / destructiveHint=false.

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?

Front-loaded with the purpose, then facets in descending importance. Dense and clause-heavy, with a little repetition around sync upkeep, but nearly every sentence carries 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?

For a six-parameter, dry-run-by-default write path with an output schema, the description covers the decision model (reviewer decides), defaults, side effects, warnings, and audit behavior. Nothing essential to correct invocation 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 the baseline is 3. The description reinforces qid's default and the note's reviewer-facing purpose and adds behavior for the 'take' handles option, but most of this duplicates the schema text.

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: 'Propose ... what a Wikidata item says for an entry,' and enumerates the fields it can carry (handles, title, subtitle, description, image). An agent can distinguish it from generic propose_* siblings, though it never names 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?

Gives clear conditional usage: qid defaults to the linked item and proposes handing values to the sync; for another item it copies them; default dry_run is true. It does not name alternative tools (propose_wikidata_changes, propose_wikidata_correction, create_entry_from_qid) so the agent must infer when to route elsewhere.

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

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

Goes well beyond the annotations: pause-state refusal (not_accepting), duplicate-on-item refusal, 409 qid_merged with the surviving QID in wikidata_item, 15-minute duplicate-suppression returning the first result, auditing, and dry-run-by-default behavior. It also discloses the non-obvious side effect that related entries auto-cross-link on approval, which no annotation conveys.

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?

Front-loaded with the core action, then refusal conditions, then dry-run semantics — a sensible ordering for a dense single paragraph. It is on the long side and sentences such as the related-entries linking clause require re-reading, but nearly every clause carries operational information an agent 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 10-parameter mutation with conditional refusals, this covers preconditions, failure modes, idempotency/dedup windows, dry-run preview contents, and post-approval side effects. Return-value description is unnecessary because an output schema exists.

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 70%, so the schema carries most of the weight, but the description adds genuine meaning: what `note` is for (reviewer-facing rationale), the semantic effect of omitting `qid`, how `let_wikidata_manage` interacts with qid, and the instruction to write titles as plain text because of auto-linking. Parameters like `subtitle`, `description`, and `handles` get no description-level elaboration, 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?

The first clause names the exact action and its destination: a proposal queued for a reviewer, visible in Console → Applications under Quick proposals, going live on approval. That is a specific verb+resource plus lifecycle, and it is clearly distinct from siblings like create_entry_from_qid or propose_from_wikidata, which are not described as reviewer-queued proposals.

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

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

It gives explicit selection criteria for the qid parameter (omit for entities with no Wikidata item; include to link) and explains the account-permission condition ('unless this account may create entries itself'). What it lacks is a direct naming of the sibling alternative an agent should pick instead when it does have a Wikidata item and wants an import path, so it stops short of full routing guidance.

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

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

The description goes far beyond the annotations, disclosing that nothing is written to Wikidata (only a proposal filed), dry-run-by-default semantics, the review/untick workflow, per-change ordering and stop-on-failure behavior, adoption and dismissal rules with exact 409 codes (`already_proposed`, `dismissed`), and the automatic P856/P407 website-language steps. This is exceptional behavioral disclosure and is consistent with readOnlyHint=false and destructiveHint=false.

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 content is a single uninterrupted wall of text of several hundred words with no paragraph breaks or headings, mixing purpose, permissions, error semantics, and dry-run output into one stream. While most information is relevant, the lack of structure makes it hard to scan, and some output-related detail duplicates what the output schema already covers.

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 complex, high-stakes mutation tool with nested objects, the description leaves nothing an agent needs uncovered: permissions, ordering, failure semantics, adoption/dismissal, rate limits, and dry-run output fields are all addressed. It is complete, even arguably more thorough than required given the presence of an output schema.

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

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

At 67% schema coverage, the description compensates substantially, especially for the `changes` array whose items are essentially open (`additionalProperties: {}`, only `action` constrained): it names all valid actions, the fields each change carries, the `statement_guid`/`step:N` cross-reference, and per-change `evidence`. `qid`, `kind`, and `evidence.why` are all explained with meaning beyond the schema, though a few details are delegated to 'as propose_wikidata_correction takes them' rather than stated inline.

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 opening clause states a specific verb and resource: 'Propose several changes to one item ... as ONE proposal.' It also implicitly distinguishes from the sibling propose_wikidata_correction by noting each change is exactly what that tool takes minus qid/kind/dry_run. The purpose is clear but somewhat buried in a very long first sentence with nested parentheticals.

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 rather than stated: the multi-change grouping, the 'administrators who may approve Wikidata edits' precondition for create_item flows, and the 200/day trusted-editor limit. There is no crisp 'use this when X, use propose_wikidata_correction when Y' routing statement, so the agent must infer the boundary between this and the single-change sibling.

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 only say readOnlyHint=false, destructiveHint=false, idempotentHint=true; the description goes far beyond them, disclosing that nothing is written to Wikidata, that approval is out of scope for this server, the trusted-editor 200/day (UTC) limit, the audit trail, the dry-run default, and the full set of refusal and warning codes with their `message`/`suggestion` payloads. This is exactly the behavioural context annotations cannot carry.

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 body is a single multi-thousand-word run-on paragraph with semicolons and em-dashes carrying clause after clause; there is no heading, list or paragraph break across dozens of distinct action modes. Only the first sentence is front-loaded and readable; the rest is effectively unparseable for an agent trying to locate the rules for one action, so the material does not earn its place in this form.

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 28 parameters, 18 actions, nested value/reference/qualifier objects, an output schema and annotations, this is an exceptionally complex tool and the description is comprehensively complete — it names dry-run outputs (`reference_snaks`, `statement`, `replaces`, `adopts`, `joins`, `website_languages`), every refusal code, and every downstream VH sync consequence. Nothing an agent needs in order to call it 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 coverage is already 93%, but the description adds real meaning the schema does not: that `reference` is REQUIRED for add_claim and supersede, which parameters pair with which `action`/`kind`, the JSON-precision trap at 9007199254740991, and the safe-merge conditions on `value_seen`. Not every parameter is covered narratively (`property`, `statement_guid` and several hashes rely on the schema), which keeps it below 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?

The opening sentence gives a specific verb and resource ("Propose a correction to a Wikidata statement … for an administrator to approve and make") and states the safety posture ("nothing is written to Wikidata"). It never distinguishes itself from the sibling propose_wikidata_changes, which is named once only as a batching mechanism, so an agent has no explicit rule for choosing 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?

Extensive routing exists: "To withdraw a correction without filing one in your place, use dismiss_wikidata_correction," dry-run-by-default behaviour, the 409 `dismissed` → `refile: true` path, and per-kind refusal conditions that effectively state when-not. What is missing is an explicit "for single corrections use this, for batches use propose_wikidata_changes" contrast with the real sibling.

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

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

Goes well past the annotations by disclosing side effects and constraints the agent cannot infer from structured fields: the applicant is emailed both reason and note, the note lands on the application thread, the action is audited, and it is irreversible though the applicant may reapply. This is consistent with destructiveHint=true and idempotentHint=false and adds real operational context.

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

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

Three tight sentences, front-loaded with the action and its side effects, then the irreversibility warning, then the dry-run safety workflow. Every clause carries information an agent needs; 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?

For a destructive, confirmation-gated mutation the description covers side effects, reversibility, audit, and the dry-run/confirm protocol, and an output schema exists so return values need no explanation. The only shortfall is the lack of explicit contrast with the other application-disposition siblings.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that confirm must equal the application's id (the schema only says 'this change's exact target'), and ties reason/note to the emailed-to-applicant behavior. The dry_run default is restated rather than clarified, so it is not a full 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 resource ('Decline an open application') with the required inputs and its scope ('open application'), clearly separating it from approve_application and mark_application_spam in the sibling list. An agent knows exactly what this does 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?

The 'open application' qualifier implies the precondition, and the dry-run-default workflow tells the agent how to actually execute. It does not, however, explicitly distinguish this from adjacent siblings like mark_application_spam or comment_on_application, so the routing guidance is clear but not exhaustive.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description adds genuine new context: reports land in 'Console → Reports', are 'Audited', and the operation is 'Dry run by default'. It doesn't restate the schema's dry_run details, adding destination and auditability instead.

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?

Front-loaded with the core action, then organized by reason. It is dense with colon/dash clauses and runs fairly long, but nearly every clause is load-bearing (media_id rules, note requirement, dry-run default), so it stays efficient rather than 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?

An output schema exists so return-value explanation is unneeded, and the description covers the remaining essentials: the reason taxonomy's least obvious cases, the note/media_id coupling, and the audited dry-run-default behavior. An agent can call this correctly without opening anything else.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds cross-parameter semantics the schema lacks: which reason forces media_id, that `image` needs a note stating ownership and the change, and that `image_link` defaults to the first image with a link and preserves the link as-is.

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 ('Report an entry to the Verified Handles team') and anchors it to a familiar surface ('as its page's Report form does'). It also distinguishes the reporting pathway from the direct mutation siblings by explaining that delete/merge are achieved by reporting as `incorrect` or `other`.

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

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

Gives clear conditions for the tricky reasons: `image` requires a media_id and an ownership note, `image_link` applies only to an image with a link (referencing get_entry's images[].link), and delete/merge should be reported as `incorrect`/`other`. It stops short of explicitly naming sibling tools like delete_entry or merge_entry as alternatives to avoid, leaving some routing to inference.

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

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

Annotations already cover readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is partly given. The description adds genuinely new behavior: no reviewer acts afterwards, the submission cannot be reopened, the action is audited, and dry_run is on by default and merely validates ownership plus open state. That is meaningful consequence disclosure beyond the structured fields.

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

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

The core action and its precondition are front-loaded, followed by the consequence, the ownership constraint, and the dry-run note. It is dense but every clause carries information; the telegraphic fragments ('Audited.', 'Only your own, whatever the key’s role.') are terse yet readable.

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

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

An output schema exists, so return values need no explanation, and annotations carry the safety flags. Combined with the stated preconditions, irreversibility, audit trail, and dry-run behavior, an agent has everything needed to invoke this two-parameter tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: it explains that dry_run reports whether the submission is yours and still open, i.e. what the preview actually validates, and reinforces that id must refer to the key's own submission.

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 — withdrawing one of the key's own submissions — plus the scoping condition (still open, own account only). An agent can distinguish this from review_submission, comment_on_my_submission, or list_my_submissions without opening any schema.

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

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

Gives clear preconditions: the submission must still be open (awaiting a reviewer or your answer), it must belong to the key's account, and the key's role doesn't matter. It stops short of naming alternatives such as review_submission for cases where the submission is no longer open, so it is strong context rather than an explicit when-not routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered; the description adds substantial context beyond that: it is 'Audited', defaults to dry run, and explains that an approval is applied as an edit where 'a conflict with a later edit is answered, not applied'. The confirm/confirmation requirement for real writes is also disclosed. Minor gap: no mention of rate limiting or what the dry-run output looks like.

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 routing constraint is front-loaded in the first clause, which is good, but the rest is delivered as two very long run-on sentences with heavily nested parentheticals that are hard to parse. Every clause carries information, yet the structure impedes quick scanning more than it needs to.

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 high-complexity tool with an output schema (so return values need not be explained), the description covers the decision set, the source queues, the dry-run default, audit logging, conflict behavior, and the application-queue alternative. The remaining gap is the absence of any note on permissions required to decide submissions or on pagination/batching of the queue.

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 description meaningfully supplements it: it clarifies that `reason` belongs only to rejecting an application (not to this tool's own reject decision), that `confirm` must hold 'this change's exact target, as the dry run gives it in `confirm`', and that `note` is the reject/spam reason or the reply to a reporter. The cross-tool dependency between dry_run and confirm is genuinely beyond the schema text.

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+resource ('Decide one waiting submission') and enumerates the four decision outcomes (approve, reject, spam, resolve), each tied to a concrete artifact (proposed change, new entry, report). It explicitly carves out the Applications queue as a separate flow, so the agent can tell it apart from approve_application/reject_application without opening schemas.

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

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

It names the sources that feed this tool (list_review_queue or list_applications tab "proposals") and explicitly routes applications ('one waiting on the applicant too') to the sibling tools approve_application, reject_application, and mark_application_spam. When-to-use, when-not, and the alternatives are all 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?

Goes well beyond the annotations (destructiveHint/idempotentHint) by disclosing irreversibility ("cannot be brought back"), immediacy ("stops working at once"), audit logging, the dry-run-by-default posture, and what the dry run reveals (key list, no more than a public prefix, whether the key is the current caller's). This is exactly the context an agent needs before a destructive call.

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?

Front-loaded with the action and its consequence, then scope, then the dry-run/confirm workflow. Dense with em-dashes and parentheticals, and the final sentence partially restates the schema's dry_run/confirm semantics, so it is informative but not maximally tight.

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, idempotent mutation with an output schema, the description covers irreversibility, permissions, audit, and the dry-run-to-confirm workflow. Nothing an agent needs to invoke it safely is missing, and return-format detail is correctly delegated to the output schema.

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

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

Schema description coverage is 100%, so the 3 baseline is already met by the schema. The description adds meaning the schema does not: `sub` implies a cross-account operation gated on "the permission to manage users," and it ties `confirm` concretely to the key's id rather than a generic target value.

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 ("Revoke an API key") and immediately scopes the blast radius: anything using the key stops working and the key is unrecoverable. It also disambiguates the two target modes (your own key vs. another account's via `sub`), so an agent knows exactly what object is affected.

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

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

Gives clear preconditions rather than alternatives: `sub` requires "the permission to manage users," and the real mutation requires the dry run first plus `confirm` set to the key's id. No sibling alternative is named, but no equivalent sibling exists in the toolset, so the contextual guidance is adequate.

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 cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower; the description still adds real behavior: exact file names rank first and it can surface very recently uploaded files. It does not discuss pagination, result limits, or licensing/rate constraints.

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

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

Three tight sentences with the core purpose front-loaded, followed by matching behavior and the cross-tool hand-off. Every sentence carries distinct, actionable 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 an output schema present, return values need not be explained, and the description still flags the `token` field and its destination parameter. For a single-param read tool this is complete enough to call correctly.

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

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

Schema coverage is 0% and the single `query` parameter is undocumented in the schema, so the description compensates by explaining that an exact file name is matched specially and ranked first. It stops short of describing other query syntax (e.g., fuzzy text search, case sensitivity).

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 (Search) and resource (Wikimedia Commons images) with the concrete goal of putting an image on an entry, mirroring the editor's image picker. This is clearly distinguishable from siblings like search_entries, upload_image, and set_entry_image.

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?

Makes clear when to use it (you want an image for an entry) and hands off explicitly to set_entry_image with the `commons_token` param. It does not name alternative routes such as upload_image or upload_image_from_url, so the exclusion guidance is implied 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 and openWorldHint=false, so safety is covered. The description does add meaningful behavior: which fields words match against, and that QID/VHID searches traverse links rather than matching text. It says nothing about result ordering, pagination limits, or the cap of 50 results.

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

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

One front-loaded sentence that defines the tool by analogy ("as the site search does") and then enumerates the three input forms. No filler and no repetition of the schema.

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

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

An output schema exists, so return shape needn't be described, and the read-only annotation covers safety. The only material gap is pagination behavior, since limit and offset are unbounded in the description despite a 50-result cap 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 description coverage is 0%, so the description carries the full burden for query, and it does that well by enumerating the three accepted query forms. The limit and offset parameters get no mention at all, so pagination semantics 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?

A specific verb plus resource ("Search the entries") with the matching semantics spelled out, which tells an agent exactly what kind of lookup this performs. It does not name the neighboring get_entry/get_entries tools, so the distinction from exact-lookup siblings is left implicit.

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 three query modes implicitly define when to use it (word search, known QID, known VHID), which is real guidance for choosing an input form. However, it never states how this differs from get_entries or get_entry, so an agent must infer the boundary from sibling names 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false; the description adds genuinely non-obvious behavior on top: the call is audited against the key and tool, and it is a dry run by default. It also explains the replacement semantics (a picture displaces a chart). It doesn't say what happens to the previously set image's media asset when replaced with null.

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 purpose is front-loaded, but it is delivered as one very long semicolon-chained sentence mixing the image case, the chart case, the exclusivity rule, auditing and dry-run. Splitting into short sentences would make the key decision (image vs chart) easier to scan.

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, multi-modal mutation tool with a rich nested chart schema and an output schema (so return values need no explanation), the description covers both modes, removal, sourcing of the media id, audit behavior and the dry-run default. Nothing an agent needs before invoking it is missing.

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