Nssnap Community

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

No annotations exist, so the description carries the full burden and does disclose real behavior: input is trimmed, a duplicate word yields a 409 conflict, and admin rights are required. It stops short of explaining matching semantics (case sensitivity, exact vs substring) or the success response.

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

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

Four tight clauses, purpose front-loaded, then constraints, error case, and permission — zero filler. Every sentence earns its place.

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

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

With no output schema and no annotations, the description does a good job covering constraints, the duplicate-error case, and the admin precondition. It is slightly incomplete on matching semantics and the success payload, but nothing critical for 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 coverage is only 33% (only 'category' documented), so the description compensates by restating word length bounds, the severity enum values, and 'trimmed' behavior which is genuinely new information not in the schema. It does not explain what 'block' vs 'warn' actually do, but the compensation is reasonable.

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') and resource ('keyword to the moderation blacklist'), and the singular 'one' immediately distinguishes it from the sibling admin_bulk_add_keywords. An agent can tell it apart from admin_delete_keyword and admin_list_keywords 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?

The singular scope implies bulk additions belong elsewhere and 'Requires admin' gives a precondition, but no alternative is named explicitly (e.g. 'use admin_bulk_add_keywords for multiple'). Usage 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?

No annotations are present, so the description carries the full burden — and it does disclose the source and target state, the side effect (author notified), and an authorization requirement. Less strong is the absence of failure behavior (e.g., what happens if the post is not in pending_review) or whether the action is reversible.

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

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

One dense sentence with the action and state transition front-loaded, then parenthetical side effects and auth requirement. Every clause earns its place; nothing is padded.

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

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

For a one-parameter, no-output-schema mutation tool, the description covers the essential mechanics: what changes, who is affected, and what privilege is needed. It lacks error/edge-case behavior, but for a tool this simple it is close to sufficient.

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 postId parameter has 0% schema description coverage, and the description never mentions it — no guidance on which post ID is expected, whether it must reference a pending-review post, or what a bad ID yields. Only the schema's type/format/required flags carry any meaning.

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

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

States a specific verb (approve), the resource (post), and the exact state transition (pending_review → published). It is immediately distinguishable from the sibling admin_reject_post, which is the natural opposite action.

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 precondition 'post pending review' tells the agent when this tool applies, and 'Requires admin' signals the privilege needed. It stops short of explicitly naming admin_reject_post as the alternative outcome, so routing is implied rather than spelled out.

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

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

With no annotations, the description carries the full burden and does substantial work: it states the admin authorization requirement, that the action is free of charge and exempt from GitHub verification and per-user quota, that it overrides the normal auto-claim path, and that it grants a welcome bonus unless awardWelcome=false. It still omits reversibility, idempotency if the preallocId was already claimed, and failure behavior for an invalid or federated target.

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 critical facts are front-loaded in the first sentence (verb, resource, target), with rationale and caveats following. It is dense and slightly overstuffed with stacked parentheticals, but every clause carries operational information rather than 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 3-parameter mutation tool with no annotations and no output schema, the description covers authorization, side effects, quota exemptions, and eligibility constraints well. The remaining gap is the result of a successful call (e.g., what is returned or what state the domain ends in), which matters when no 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 only 67% because preallocId has no schema description; the prose compensates by clarifying it identifies a 'pending pre-reserved domain'. It also constrains username (must be a locally registered account) and explains awardWelcome's effect beyond the schema's 'grant the one-time welcome TGC bonus'.

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 ('assign'), resource ('pending pre-reserved domain'), target ('local user by username') and cardinality ('one'), which cleanly separates it from admin_assign_domain_preallocations_batch. 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?

Explicitly frames the use case: manual re-allocation that bypasses the retired email-match auto-claim, for early-registered users who never received their claim, and names the exclusion (federated shadow accounts cannot receive domains). It does not explicitly name the batch sibling as the alternative for multiple assignments, so it falls just 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?

With no annotations, the description carries the full burden and does so richly: only verified accounts receive domains, unverified/federated-shadow/unmatched entries are skipped and reported per row, assignments are free and exempt from verification and quota, 1-year term, and in-site DNS hosting replaces legacy external NS. dryRun default is disclosed.

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 packs eligibility, cost/term, DNS behavior, dryRun, and auth into dense clauses. Information-dense with little waste, though the single long paragraph is heavy.

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

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

No output schema exists, so the description must convey behavior and it does: skips are reported per row, dryRun scans only, admin required. It stops short of describing the actual report shape or pagination beyond the schema's limit note, leaving a small gap.

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

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

Schema coverage is 100% (baseline 3), but the description adds real meaning beyond it: the email-matching rule (lower(email) equality against legacy whois email), the default dryRun semantics, and the per-row skip/report behavior tied to the parameters.

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

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

States a specific verb+resource ('Batch-backfill pending pre-reserved domains to local accounts matched by email') with clear scope. The 'batch' framing implicitly distinguishes it from the singular sibling admin_assign_domain_preallocation, but the description never names that sibling 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?

Provides clear context: backfill of pending pre-reservations, requires admin, dryRun=true is the default scan-only mode. It does not explicitly state when to use this batch variant versus the singular admin_assign_domain_preallocation, so an agent must infer the 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?

With no annotations, the description carries the full burden and does disclose meaningful side effects: session clearing and login rejection until expiry. It stops short of reversibility/undo, audit logging, or whether the ban can be shortened, but the core behavioral consequence is explicit.

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

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

A single compact sentence with the action, scope, and effect front-loaded, followed by the prerequisite. Zero 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 3-required-param mutation tool with no annotations and no output schema, the description covers the effect well but omits the reason parameter's purpose and says nothing about return values or failure modes (invalid user, non-admin caller). Minimum viable, not complete.

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

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

Schema description coverage is 0%, so the description must compensate. 'N days' maps the days parameter and 'a user' implies userId, but the required 'reason' parameter (maxLength 300) gets no explanation anywhere, leaving one of three required params semantically empty.

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 ('Ban a user') and adds the temporal scope ('for N days'), making it immediately distinguishable from siblings like admin_unban_user and admin_warn_user. No ambiguity about what the tool does.

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 prerequisite 'Requires admin' gives real context for who may call it, but there is no guidance on when to ban versus warn (admin_warn_user) or how this relates to admin_unban_user. Usage is implied rather than directed.

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

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

With no annotations at all, the description carries the full burden and does so well: it discloses the delivery mechanism (fan-out through the persistent queue), idempotency on retry ('users already delivered are never re-sent'), per-admin rate limiting sharing a bucket with the web console, and the admin requirement. These are exactly the traits an agent needs before invoking an irreversible mass-send.

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 sentences, each carrying new information, with the highest-stakes facts (scope + extreme care) front-loaded before mechanism and parameter details. No filler or hedging.

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

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

For a three-parameter mutation with no output schema and no annotations, the description supplies everything: blast radius, auth requirement, rate limits, retry/idempotency behavior, and parameter constraints. Nothing an agent needs to decide whether and how to call it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by clarifying what url actually does (an optional in-site path attached to the notification, with a /hot example) and by foregrounding that title and body are the required pair. It does restate the max lengths the schema already enforces, which caps it below 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 (broadcast) and resource (system announcement), plus the exact scope (EVERY active user) and the two delivery channels (in-app notification + email). No sibling tool does anything comparable, and an agent can distinguish it immediately from per-user tools like admin_warn_user or admin_ban_user.

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

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

Gives clear operational context: 'Use with EXTREME care. One call reaches the entire user base,' and states the auth prerequisite ('Requires admin'). It does not name an alternative or a when-not condition (e.g., targeted notification vs. keyword-level messaging), so it stops short of a full 5.

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

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

With no annotations, the description carries the burden well: it discloses skip-not-error semantics for duplicates and blacklist hits, implied idempotency, the admin requirement, and that counts are returned. It does not say whether insertion is atomic/partial on validation failure or mention rate/concurrency limits, leaving some mutation behavior unspecified.

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 dense, front-loaded block: cap sentence, then parameter semantics, then return/auth notes. It is efficient with no filler, though cramming constraints into a single run-on sentence hurts scannability slightly.

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

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

No output schema exists, so it correctly states the return shape (inserted/skipped counts), and with no annotations it supplies the auth requirement and dedup rules. It omits failure-mode behavior (partial vs all-or-nothing inserts), which is the main remaining gap for a mutation tool.

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

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

Schema coverage is only 33% (just the category default), so the description must compensate and largely does: it explains words cardinality/length 'after trim', the severity values, and the category default. Much of this restates schema constraints (1-500, 1-120), so it adds only marginal meaning beyond the structured fields.

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

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

States a specific verb and resource with scale ('Import many keywords at once'), which cleanly separates it from the single-item sibling admin_add_keyword. An agent can select this over the singular tool without opening either schema.

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

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

Gives clear operating context: bulk import, dedup/blacklist rows silently skipped, and 'Requires admin' as a precondition. It never explicitly names admin_add_keyword or states when a single insert is preferable, so the alternative routing is inferred rather than spelled out.

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

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

With no annotations, the description carries the full burden and delivers: changes happen in the same transaction, the submitted website URL is carried over unverified, the pro compliance profile is reset to full score, the user is notified, the account type is untouched on reject, the applicant may reapply, and every action is audit-logged. That is well beyond what the schema or absence of annotations 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 purpose, then structured by action branch and closed with the cross-cutting facts (audit log, admin requirement). Every sentence adds new information; nothing is repeated from the schema.

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

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

For a mutation tool with no annotations, no output schema and partial schema coverage, the description supplies the missing pieces: post-action state, side effects, notification behavior, permission requirement, and audit trail. An agent has enough 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 only 33% (just the note field), so the description must compensate. It does: it explains that note is required only for reject, is 1-300 chars, and is shown to the user, and it gives semantic meaning to both enum values of action. applicationId remains implied only, which keeps it from a 5.

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

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

States a specific verb+resource ("Decide one professional-account application") and immediately enumerates the two action modes with their distinct effects. It is clearly separable from siblings like admin_list_pro_applications (read side) and admin_decide_verification (different resource), so an agent can route 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 description gives concrete conditions for each action branch (approve = admit as pro; reject = close with reason, applicant may reapply) and states the precondition "Requires admin." It does not explicitly name the listing/alternative tool to consult first, so it stops just short of full when/when-not 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?

With no annotations, the description carries the full behavioral burden and does so: transactional badge write on approve, immediate badge clearing plus retained audit row on revoke, notification on every path, audit logging, and the HIGH-IMPACT irreversibility warning. An agent learns the destructive consequences and permission needs it would otherwise have to guess.

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 with the core verb, then organized by 'action=X:' labels so each sentence maps to a decision branch. The paragraph is long for a 3-parameter tool and could be split, but no sentence is redundant.

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

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

Given no output schema and no annotations, the description covers outcomes, side effects, auth, and audit trail well for a 3-param mutation tool. It omits error/edge behavior (already-handled or nonexistent requestId) and does not explain requestId's origin, which admin_list_verifications presumably supplies.

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

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

Schema coverage is only 33%, so the description must compensate, and it does by defining each `action` enum value's semantics and explaining the `note` value (reason text shown to the user, 1-300 chars). Minor friction: the description frames the note as generally 'required' while the schema marks it optional and scoped to reject only, leaving `requestId` entirely unexplained.

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

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

States a specific verb ('Decide') and resource ('one verification request'), then enumerates the three mutually exclusive outcomes. It is clearly distinguishable from siblings like admin_list_verifications, admin_grant_badge, and admin_revoke_badge without opening any schema.

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

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

The action branches effectively tell the agent when each mode applies (approve/reject a pending request, revoke an already-approved one), and 'Requires admin' sets the precondition. It never names alternative tools (e.g., admin_grant_badge / admin_revoke_badge) as the path for directly manipulating badges, so routing is inferred rather than explicit.

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

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

With no annotations, the description carries the full burden and does disclose the two most important traits: the operation is a soft delete (status=deleted, implying reversibility rather than destruction) and it requires admin privileges. It omits whether the comment is hidden from regular users, whether there is a restore path, and what the call returns.

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

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

Two short clauses, front-loaded with the action and its safety-relevant nature. No filler whatsoever.

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

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

For a two-parameter mutation with no annotations and no output schema, the description covers purpose, soft-delete semantics, and auth requirement, but leaves the 'note' parameter and the result of the call unspecified. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate, yet it says nothing about either parameter. 'commentId' is self-evident from its uuid format, but 'note' (a 300-char string) is entirely unexplained — an agent must guess whether it is a deletion reason, an internal memo, or something else.

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

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

Names a specific verb and resource ('Soft-delete a comment') and clarifies the semantics with 'status=deleted', which distinguishes it from a hard delete. It does not, however, differentiate itself from the many other admin_delete_* siblings (media, pin, keyword, feature card) beyond the resource name.

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

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

'Requires admin' states a prerequisite but is not usage guidance — it says nothing about when to use this instead of a hard delete, a moderation action like mod_decide_delete_request, or a list/search comment tool. No alternatives or exclusions are given.

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

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

With no annotations, the description carries the full burden and does useful work: it discloses that per-locale translations and user confirmation records are cascade-deleted and that confirmation audit points are removed with the card, plus the admin auth requirement. It omits irreversibility/reversibility and rate-limit context, keeping it short of a 5.

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

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

A single front-loaded sentence with a parenthetical that adds cascade detail rather than filler. Efficient, though the parenthetical is dense and could be split for readability.

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 one-param tool with no annotations and no output schema, the description covers the essential facts an agent needs: target identification, auth requirement, and destructive blast radius. Only irreversibility confirmation 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?

One non-required-field parameter with 0% schema description coverage means the description should compensate. 'By id' minimally clarifies that cardId identifies the target card, but adds no format or semantic detail beyond what the schema's uuid type already conveys.

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 (feature intro card), scoped to a single item by id. This clearly distinguishes it from the sibling admin_upsert_feature_card and admin_list_feature_cards without needing to open any schema.

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

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

The description implies usage via 'by id' and the 'Requires admin' precondition, but never states when to reach for this over alternatives (e.g. upsert to modify, list to inspect). Usage is implied rather than explicitly routed.

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

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

With no annotations, the description carries the full burden and does disclose the admin authorization requirement, which is meaningful behavioral context. It does not, however, state that the removal is irreversible, what happens if the id does not exist, or what the caller receives back - omissions that matter for a destructive mutation.

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, purpose first, prerequisite second, with no filler. Nothing redundant 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?

For a single-parameter destructive admin tool with no output schema, the description covers purpose, scope, and authorization, which is most of what an agent needs. The remaining gap - irreversibility and not-found behavior - is minor but real for a delete operation.

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

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

Schema description coverage is 0%, so the description must compensate for the single keywordId parameter. 'By id' confirms the identifier's role and that exactly one is expected, but adds no detail on the UUID format already declared in the schema or where the id is obtained.

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 - 'Remove one keyword from the moderation blacklist by id' - which is unambiguous and self-contained. The 'one keyword' scoping also implicitly distinguishes it from admin_bulk_add_keywords and admin_list_keywords among the siblings.

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

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

The description states the precondition 'Requires admin', which is useful routing context, but gives no explicit when-to-use guidance or naming of alternatives (e.g., use admin_list_keywords to find the id first). Usage is implied by the operation name rather than spelled out.

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

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

With no annotations, the description carries the full burden and does so well: it enumerates what is destroyed (library row, user avatars/covers and post covers referencing the file, the storage object), notes a retry mechanism via a cleanup queue when storage is unavailable, and states the action is audit-logged. That is unusually complete destructive-behavior disclosure.

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 destructive action and scope in the first clause, then layers side effects, retry semantics, audit logging and the auth requirement as short trailing sentences. Nothing is padded or repeated.

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

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

For a one-parameter destructive admin tool with no annotations and no output schema, the description covers effects, retry behavior, audit trail and authorization. It stops short of describing return/error behavior or confirming irreversibility guarantees, which is a minor gap rather than a blocking one.

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

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

Schema coverage is 0% and mediaId's UUID format is undocumented, but the description conveys the key semantic that exactly one media file is targeted ('one media file', singular). It adds marginal meaning but does not explain the identifier's origin or expected failures for unknown IDs.

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

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

States a specific verb and resource plus the scope: 'Permanently delete one media file site-wide.' The phrase 'site-wide' and 'Requires admin' implicitly separate it from the sibling delete_media (user-scoped) and from admin_list_media, so an agent can route correctly 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 one clear precondition ('Requires admin') but never states when to choose this over delete_media or list_my_media, nor when deletion is inappropriate. Usage is implied by the site-wide/admin framing rather than explained.

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

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

With no annotations, the description carries the full burden and does well: it discloses the operation is a hard (irreversible) delete, that it takes effect immediately, that a missing pin returns 404, and that admin rights are required. It does not mention any audit/idempotency or response behavior, but the key destructive and auth characteristics are covered.

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 with the verb first, a parenthetical that earns its place by preventing unnecessary deletions, plus compact error and auth clauses. No waste.

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

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

For a single-parameter delete with no output schema or annotations, the description covers action, irreversibility, auth requirement, and error semantics. Only the return behavior (does it return the deleted pin or just success?) is unaddressed, which is 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?

The single pinId parameter has 0% schema description coverage, so the description must compensate. 'Remove one site-wide pin' implies the ID identifies a pin, but no format, source of the ID, or lookup guidance (e.g., from admin_list_pins) is given. Adequate but minimal.

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 (Remove) and resource (site-wide pin) with scope qualifier (immediately, hard delete). The 'site-wide' qualifier implicitly distinguishes it from post-level pin siblings like mod_pin_post/mod_unpin_post, but no sibling is named explicitly, so it falls short of a 5.

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

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

Provides clear context for use and a useful when-not hint: 'expired pins already drop out of queries on their own' tells the agent it need not delete expired pins. It does not explicitly name admin_set_pin as the alternative for replacing/re-pinning, 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?

With no annotations, the description carries the full burden and does so well: it declares the operation irreversible, that the record cannot be recovered, that pending retries are cancelled, that the action is audit-logged, and that admin privileges are required. These are exactly the traits an agent needs before invoking a destructive tool.

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

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

Four short sentences with the destructive scope front-loaded and zero filler; the irreversibility warning, parameter requirements, audit note, and auth note each earn their place.

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

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

For a two-parameter destructive tool with no annotations and no output schema, the description covers reversibility, side effects on retries, auth requirements, and audit trail — everything needed to call it safely and 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%, with both parameters (id, queue) documented in the schema itself, so the baseline is 3. The description adds only the relational note that the queue name is where the id lives, and provides no format, examples, or lookup guidance beyond that.

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

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

States a specific verb (delete) plus resource (one pg-boss job) and scope (single, permanently), which cleanly separates it from admin_list_queue_jobs and admin_retry_queue_job in the sibling list. An agent can classify this as an irreversible single-record mutation 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 preconditions (requires queue name and id, requires admin) and the consequence 'pending retries will never run again' implicitly contrasts with admin_retry_queue_job. It never explicitly names the retry alternative or states when not to delete, 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?

With no annotations, the description carries the full burden and does well: it discloses service-layer enforcement of the state machine, the 1-500 character note requirement for terminal statuses, the admin requirement, and the notable side effect that a result email goes to the reporter with an English default. It omits error behavior, idempotency, and reversibility of a transition.

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?

Every sentence earns its place: allowed values and the forbidden transition come first, then enforcement and note rules, then the email side effect and the admin gate. No filler or restatement of the tool name.

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

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

For a 3-parameter mutation tool with no annotations and no output schema, the description covers purpose, constraints, permissions, and a side effect. The remaining gap is what the call returns and whether repeated transitions are idempotent, which the absent output schema leaves unexplained.

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

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

Schema description coverage is only 33%, so the description must compensate, and it does for the two parameters that matter: the allowed values of `to` and the note's requirement and 1-500 character length. Only `reportId` is left to the schema's uuid format, which is self-evident from the name.

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 (transition) and resource (abuse report) plus the exact set of legal target values (reviewing | resolved | rejected), which distinguishes it from read-only siblings like admin_list_domain_abuse and from the more general admin_domain_moderate. The state-machine constraint further pins down what the tool is for.

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

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

Gives clear operating conditions: which transitions are permitted (no return to pending), that terminal statuses demand a note, and that admin privileges are required. It stops short of naming an alternative tool (e.g. where to list reports first) or explicitly stating when not to call it.

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

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

With no annotations, the description carries the full burden and does so richly: per-action preconditions and 409 failures, owner notification on suspend/release, preserved NS/DS config, immediate-delete semantics for enforce=true, idempotent ledger refund, and audit logging. An agent knows the blast radius and side effects before calling.

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 block, but every sentence earns its place and it is front-loaded as action=... clauses that an agent can scan. Bulleted per-action formatting would be marginally clearer than the run-on prose, but there is no filler.

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

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

For a 5-action fan-out tool with no annotations and no output schema, the description covers preconditions, failure codes, side effects, idempotency, authorization, and audit behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 60% and the description supplements it: note is scoped to suspend/activate/release, amount is required as a positive integer for refund, and enforce=true is explained as immediate delete with the label freed. Only domainId is left implicit (self-evident as a UUID).

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 (moderate) and resource (one domain registration), then enumerates all five action modes with their individual semantics. An agent can distinguish this from siblings like admin_domain_abuse_transition, domain_update_ns, or admin_get_domain_registration 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 explicit when/when-not per action (suspend only active domains else 409; activate only suspended; release 409 if already released; resync 409 for released) and states the admin prerequisite. It does not route the agent to alternative tools for adjacent tasks, which is the only missing piece for a 5.

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

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

No annotations are present, so the description carries the full burden and does so well: it discloses the single-transaction nature, the exact blast radius ('invisible site-wide, feed, interactions and every session-bound surface'), reversibility via restore, audit-trail side effect of the note, and the admin prerequisite. These are precisely the traits an agent needs for a destructive mutation.

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-resource pair followed by effect, reversibility, side effects and prerequisites in a tight four sentences. There is minor redundancy between 'until restored' and 'action=restore lifts the suspension', but nothing inflating the description.

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

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

For a 3-param destructive tool with no output schema and no annotations, it covers safety profile, effect scope, reversibility and authorization. Gaps remain around return/success shape and behavior on an already-suspended actor (idempotency) or on unknown actorIds, which matter somewhat for a transactional mutation.

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

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

Schema coverage is 67% and the description fills the gap on the undocumented action enum by explaining what suspend and restore each do, plus the audit-trail effect and 300-char cap of note. It adds real meaning beyond the schema, though it doesn't restate the actorId UUID format/origin constraint.

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 pair and resource: 'Suspend or restore one remote fediverse actor.' It explicitly scopes the target to remote fediverse actors, which separates it from local-user tools like admin_ban_user and admin_unban_user. An agent can select 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?

It clearly defines the two action values and their effects, and the 'same semantics as a local user ban' cue implicitly tells the agent this is the federation counterpart to admin_ban_user. It never states when NOT to use it or names a sibling alternative for related federation tasks (e.g. admin_domain_moderate), so it stops short of explicit 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?

With no annotations, the description carries the full burden and does well: it discloses ordering, the admin join, that system actors surface with null adminId, an explicit authorization requirement ('Requires admin'), and return contents. Missing only things like pagination behavior or rate limits.

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

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

Four tight sentences, front-loaded with the core purpose and scoping/ordering before the filter details and the auth caveat. 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?

No output schema exists, so the description rightly spells out the return shape (audit rows + total + distinct action list) and the admin prerequisite. Everything needed to call it correctly is 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 coverage is only 50%, but the description compensates by clarifying action is an exact match with concrete examples (settings.update / domain.release) and that adminId relates to system actors having null. limit/offset are left to the schema's defaults and bounds.

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

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

States a specific verb (Read) and resource (audit log / admin actions in mod_logs), plus ordering (newest first) and the join (acting admin). This is clearly distinguishable from lookalike siblings like admin_list_mail_log or admin_list_ops_snapshot.

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 optional filters and what the distinct action list is for (filter dropdowns), giving implied usage. But it names no alternatives and states no when-to-use or when-not conditions relative to the other admin log/list tools.

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

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

With no annotations, the description carries the full disclosure burden and does reasonably well: it declares read-only semantics, states the admin authorization requirement, and enumerates the returned state (configured flag, cron, retention, in-progress, last run, 25 recent runs with trigger/status/size/duration/error). It omits error behavior and any rate/refresh considerations, but covers the key traits.

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

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

A single front-loaded sentence that opens with the purpose and then enumerates return fields; every listed field is informative rather than filler. It is dense and list-heavy, but no sentence is wasted.

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

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

Because no output schema exists, describing the returned snapshot contents is exactly the compensation needed, and the description supplies it along with the admin requirement. An agent has everything required to call this correctly.

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

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

The tool takes zero parameters, so per the rubric this is a baseline 4. The description adds nothing to parameter meaning, which is correct since there is nothing to describe.

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

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

The description gives a specific verb+resource ('Backup panel snapshot') and immediately marks it read-only, which implicitly separates it from the write sibling admin_run_backup. It does not name the sibling explicitly, so the differentiation is inferable rather than stated.

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 only guidance is the prerequisite 'Requires admin', which is useful but does not tell the agent when to reach for this versus admin_run_backup or other admin snapshot tools (admin_get_ops_snapshot, admin_get_audit). Usage is implied by the name and read-only marker rather than explained.

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

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

With no annotations, the description carries the full burden. It discloses the auth requirement and the breadth of returned data, and 'Get' implies a read operation. It does not address error behavior for an unknown boardId, rate limits, or whether the roster can be empty – meaningful gaps for a tool with zero annotation coverage.

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

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

A single dense sentence, appropriately front-loaded with the verb and resource before the payload enumeration. No filler, though the parenthetical list of returned fields makes it longer than strictly necessary.

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

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

For a one-parameter getter with no output schema, the description usefully previews the return payload and states the admin prerequisite. The remaining gap is failure/edge-case behavior, which is minor at this complexity.

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

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

Schema coverage is 0%, so the description technically has to compensate, and it does not explain boardId beyond the reference to 'one board'. The parameter is a single self-evident UUID identifier whose type/format is already declared in the schema, so the practical cost is low.

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 ('Get one board's full profile') and enumerates the payload: policies, overrides, manual translations, and moderator roster with wage/attendance overrides. The word 'one' implicitly distinguishes it from admin_list_boards, though no sibling is named explicitly.

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

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

'Requires admin' gives a real precondition, which is more than most definitions offer. However, there is no guidance on when to use this versus admin_list_boards or admin_get_topic, and no mention of what happens on a missing/invalid board.

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

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

With no annotations at all, the description carries the full burden and does a fair job: 'Read' signals a non-mutating operation, 'Requires admin' declares the authorization requirement, and the parenthetical '(locale → {tagline, description})' discloses the nested return shape. It omits failure modes (e.g. behavior when brand is unset) but nothing is contradicted.

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

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

A single sentence that front-loads the core action, enumerates the returned fields, and closes with the auth prerequisite. Every clause earns its place, with no filler or repetition of the name.

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

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

There is no output schema, so the description must describe return values itself, and it does so concretely including the locale-keyed translation map. For a zero-parameter admin getter this is nearly complete; only edge-case behavior (unset brand, error surface) is 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?

The tool takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description adds no argument-level detail because none is needed.

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

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

States a specific verb ('Read') and resource ('site brand texts'), then enumerates the exact fields returned (name, tagline, description) plus the per-locale translation package. The get/set pairing with the sibling admin_set_brand is inferable, but the description never names that sibling, so differentiation 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 only guidance is the precondition 'Requires admin', which is useful auth context but not a when-to-use rule. It never states when to prefer this over admin_get_settings (which likely also carries brand-ish config) or that this is the read counterpart to admin_set_brand, so usage is only implied.

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

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

No annotations are provided, so the description carries the full burden, and it does materially: it discloses read-only semantics, that no audit entry is written (a real side-effect disclosure), and the admin authorization requirement. It stops short of rate limits or response-shape caveats, but this is well above the bare-minimum for an unannotated read tool.

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

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

One dense sentence, front-loaded with the verb and scope, with the return contents and the two operational qualifiers compactly bracketed. No filler 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?

With no output schema, the description correctly enumerates the returned components, and it covers the authorization and side-effect profile an agent needs before calling. Only the identifier format and the list-vs-single routing 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 description coverage is 0% on the single domainId parameter, so the description must compensate. It only implies that the ID identifies the target registration ('one domain registration's admin detail') and adds no format or identifier-source detail beyond that weak implication.

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 (Get), resource (domain registration), and singular scope ('one ... admin detail') that distinguishes it from the sibling admin_list_domain_registrations. Enumerates the composite payload (domain DTO + owner + DNS sync jobs + abuse reports), so an agent knows exactly what it returns 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 a prerequisite ('Requires admin') and non-use markers ('read-only, no audit entry'), but never names the alternative tools it competes with, such as admin_list_domain_registrations for enumeration or domains_get for the public view. Usage is implied by the admin-detail scoping 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?

With no annotations, the description carries the full burden, and it does deliver: it discloses that the call is read-only and produces no audit entry, plus the status vocabulary (active | suspended). It stops short of describing pagination, response size, or freshness of the snapshot data.

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

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

A single front-loaded sentence anchored by the verb 'Get', with the payload enumeration packed in. Dense but every clause names distinct returned data, so little 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?

For a zero-parameter tool with no output schema, the description usefully stands in for the return shape by enumerating the data categories and the actor status enum. Auth requirement is covered; only pagination/freshness remain 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?

Zero parameters, so there is nothing for the description to disambiguate — the baseline for a no-param tool. The description correctly avoids inventing parameter detail.

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

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

Names a specific verb and resource (get ... federation governance snapshot) and enumerates exactly what it returns: shadow-actor/link/follow stats, inbound activities, remote actors with status, and in-flight profile-bind verification sessions. This clearly separates it from sibling read tools like admin_get_ops_snapshot, admin_get_stats, and admin_get_audit.

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?

'Requires admin' gives a permission prerequisite, which is useful context. However, it never states when to reach for this tool over the similarly-named admin_get_ops_snapshot or admin_get_stats, leaving the choice to inference.

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

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

With no annotations, the description carries the full burden and does reasonable work: it signals a read operation, discloses the admin authorization requirement, and describes the returned data structure (locale → {name, description}). It stops short of covering failure modes, such as what happens when no guest rail copy is configured or when the translation package is absent.

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

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

A single efficient sentence with the action and resource front-loaded, followed by a parenthetical defining the resource and the exact return shape. No filler, no restatement of the tool name.

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

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

With no output schema, no annotations, and no parameters, the description is the only source of behavioral information, and it covers the essentials: auth requirement and return payload shape. Missing only edge-state behavior, which is a minor gap for a simple zero-arg getter.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. It correctly avoids inventing parameter discussion and instead spends its words on the returned payload.

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 (Read) and a precisely defined resource (the guest rail join-invite copy), then clarifies what that is by naming its audience: copy shown to logged-out visitors. It also enumerates the exact content returned (baseline title/description plus the per-locale translation map), which cleanly separates it from the write-side sibling admin_set_guest_rail.

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

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

The description gives one hard precondition ('Requires admin') but never states when to reach for this tool versus the obvious sibling admin_set_guest_rail or other content getters. Usage is implied by the get/set naming pair rather than stated explicitly.

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

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

With no annotations, the description carries the full behavioral burden and does well: it declares the operation read-only, states the admin requirement, warns that storage figures are budgeted (~2s) with partial results marked complete:false, and explains that dns stats are null unless DNS_STATS_CH_URL is configured. This conditional/partial-result disclosure is genuinely useful; only the absence of a return-shape summary keeps it from a 5.

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

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

Front-loads the purpose before the section list, and every clause earns its place by naming a distinct data section. The single very long sentence with nested parentheticals is dense and slightly hard to scan, which costs it the top mark.

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

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

For a no-parameter tool with no annotations and no output schema, the description does the heavy lifting by enumerating all returned sections and their edge cases (partial storage, null dns stats). It is essentially complete, though it does not note an auth failure mode or the response envelope.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning for the description to add or omit. Nothing about arguments is left ambiguous.

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

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

Uses a specific verb+resource ('Read-only operations snapshot') and enumerates the exact sections it returns (worker process info, row counts, queue depth, content health, storage, dns stats), which effectively separates it from admin_get_stats and admin_get_federation_snapshot. It stops short of naming any sibling explicitly, so it lands at 4 rather than 5.

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

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

Implies its usage context ('for the ops console') and states a prerequisite ('Requires admin'), which is more than nothing. However, it gives no when-to-use/when-not guidance and never contrasts itself with the many other admin_* and get_stats-style read tools, leaving the agent to infer the choice.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the masking contract for return values (apiKeys -> hasKey, clientSecret -> hasSecret, smtp pass -> hasPass, secrets never returned in plaintext), the parsing of i18n packages into objects, and the admin authorization requirement.

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 and packed with genuinely useful detail, but it is one long semi-colon-chained sentence; the masking rules could be broken out for readability. Little waste, though density hurts scanability slightly.

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

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

For a tool with no output schema and no annotations, the description compensates by explaining exactly how return values are transformed (masked secrets, parsed i18n objects) and what authorization is required. 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% and the single `keys` parameter is fully documented there, including 'unknown keys are ignored' and 'omit for all keys'. The description largely restates that, adding only emphasis on the default behavior, so baseline 3 applies.

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

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

States a specific verb+resource ('Read site settings') and immediately defines the scope ('full key set by default; optional `keys` subset'), which cleanly separates it from the write-side sibling admin_set_settings. An agent can tell what it 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?

Gives clear operating context: default full-key behavior, how to narrow via `keys`, that unknown keys are ignored, and the hard prerequisite 'Requires admin'. It stops short of naming alternative readers (e.g. admin_get_brand/admin_get_guest_rail for narrower scopes) or stating when-not to use it.

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

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

With no annotations, the description carries the behavioral burden. It does disclose the auth requirement ('Requires admin') and the read-only nature implied by 'stats', and enumerates the returned metrics in the absence of an output schema. It does not state caching/refresh behavior or whether the counts are live, which is a moderate gap for a stats endpoint.

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

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

Two short sentences, zero waste, with the scope and metric list front-loaded before the access requirement. Nothing is padded or repeated from the name.

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

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

For a zero-parameter, no-output-schema read tool, the description supplies the returned metric set and the admin prerequisite, which is most of what an agent needs. Only the live-vs-cached nature of the numbers is 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?

The tool takes zero parameters, so the description needs no parameter detail; the baseline for a parameterless tool applies. The parenthetical metric list adds useful framing about what is being measured even though there is nothing to configure.

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 (get) and resource (site-wide operating stats) and enumerates the exact metrics returned: users, posts, comments, open reports, pending review. It is distinguishable from the write-oriented admin siblings, but it never contrasts with the similar-sounding read tools get_stats or admin_get_ops_snapshot.

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 only usage signal is the precondition 'Requires admin', which tells the agent who may call it but not when to prefer it over get_stats, admin_get_ops_snapshot, or admin_get_audit. No when-to-use or when-not-to-use guidance is given.

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

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

With no annotations, the description carries the full burden. It does disclose the admin authorization requirement and that the read returns a full profile plus all manual translations, which is real added context. It says nothing about failure modes (unknown topicId), caching, or whether translations include non-manual/auto ones, leaving gaps for an unannotated tool.

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

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

One dense sentence that front-loads the action and resource, then the return shape, then the permission requirement. No filler whatsoever.

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

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

For a single-resource read with no output schema, the description covers the operation, the permission gate, and the shape of the returned translations map. What is missing is minor: error behavior for an invalid/unknown topicId.

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

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

The single parameter has 0% schema description coverage, so the schema only supplies the name and uuid format. The description implies topicId selects the topic being fetched but adds no format or resolution semantics beyond that; adequate but thin.

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 ('Get one topic's full profile') and even names the payload contents (manual translations keyed by locale). The word 'one' implicitly separates it from admin_list_topics, but no sibling is named explicitly, so it stops short of a 5.

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

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

'Requires admin' gives a useful precondition, and the singular 'one topic' implies this is the detail-fetch counterpart to admin_list_topics. However, no when-to-use or when-not-to-use guidance and no alternative (e.g. admin_list_topics, admin_upsert_topic) is referenced.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the 409/idempotency outcome, that the user receives a congratulation notification, that federated ghost accounts auto-wear the badge because they have no session, and that the wear limit of 3 still applies. This is exactly the kind of side-effect and edge-case context an agent needs for a privileged mutation.

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 paragraph that front-loads the verb, resource, and required inputs before moving to idempotency and side effects. Every sentence carries information, though the length pushes the practitioner-relevant warning (auto-wear, wear limit) toward the tail rather than near the top.

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 privileged mutation with no annotations and no output schema, the definition covers auth requirement, idempotent failure mode, notification side effect, and the federated-account edge case. It could be slightly stronger by stating what a successful response returns or where badgeId is sourced, but the essentials 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 coverage is 67%, with note and username already documented in-schema. The description adds genuinely new detail: username is case-insensitive and 1-63 chars (schema only gives maxLength 63, no min or casing), and note is optional with a 200 max. badgeId is only identified by name/format, with no hint that it comes from admin_list_badges, leaving a small 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 ('Grant a badge to a user') and the keying mechanism (by username), which cleanly separates it from siblings like admin_revoke_badge, admin_list_badges, and admin_upsert_badge. An agent can distinguish it from those 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 context: 'Requires admin' and the idempotency guard ('granting again to a holder returns 409 already_granted'), which effectively tells the agent not to re-call for existing holders. It stops short of explicitly naming the alternative (e.g. admin_revoke_badge) or stating when-not to use it, so it earns a 4 rather than a 5.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the admin authorization requirement, the deterministic sort (sortOrder then creation time), and the localization fallback chain (ext_badge_translations -> en -> zh baseline). It omits pagination/result-size behavior, which is the only notable gap for a catalog endpoint.

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 and sort behavior, then the returned field list, then localization and auth. The field enumeration makes the middle sentence dense, but every clause carries information an agent would otherwise have to infer.

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

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

No output schema or annotations exist, so the description must describe the return shape, and it does (key, baseline zh name/wear-text/icon/style/description, enabled flag, grant counts). Combined with the localization note and admin requirement, it is nearly complete; only paging/limits are 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?

The tool takes zero parameters, so per the rubric the baseline is 4. Nothing in the description is needed to disambiguate inputs, and it correctly avoids inventing parameter semantics.

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

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

States a specific verb+resource ("List the badge catalog") and further narrows scope with per-badge grant counts and sort order, making it unmistakable against mutating siblings like admin_upsert_badge, admin_grant_badge or admin_revoke_badge. An agent can tell exactly what this returns without opening anything else.

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 list verb and the "Requires admin" prerequisite, but there is no explicit when-to-use framing, no mention of alternatives, and no guidance on when to prefer this over e.g. admin_list_perks or a search tool. Minimum-viable rather than instructive.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the returned fields (policies, display order, post counts, translations) and the admin requirement, but says nothing about pagination, ordering guarantees, or volume, which matters for a bulk list endpoint.

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 that front-loads the scope ('including inactive ones') and then enumerates returned fields; there is no filler. The parenthetical nicely compresses the translation shape.

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

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

With no output schema and no annotations, the description does the work of signaling key return fields and the admin gate, which is adequate for a no-param list tool. It stops short of covering pagination or per-record nesting limits, 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. Nothing in the description conflicts with the empty schema.

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

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

States a specific verb and resource ('List all boards') and adds scope that distinguishes it from siblings: it includes inactive boards and requires admin, unlike the public list_boards/search_boards. An agent can tell this apart from admin_get_board (single board) and admin_list_topics 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?

The 'Requires admin' clause implies the admin context and the inactive-inclusion hints at when this is preferred over public listing, but it never names an alternative or an explicit trigger condition. Usage is inferable rather than stated.

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

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

No annotations exist, so the description carries the full burden. It does disclose a real behavioral trait — the admin authorization requirement and the moderation viewpoint — which is useful. It omits ordering/'latest' semantics, pagination behavior, and what the moderation view actually returns, so the coverage is partial.

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

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

Two short sentences, zero filler, with the resource and scope front-loaded ahead of the prerequisite. Nothing is redundant.

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

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

With no annotations, no output schema, and 0% parameter coverage, the description should say more about return shape, ordering, and pagination. As written it is adequate for picking the tool but thin for calling it confidently.

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

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

Schema coverage is 0%, so the description must compensate. It hints at the status parameter ('with status') but adds no value beyond the schema's own enum values, and the limit parameter is undocumented in both description and schema.

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

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

States a specific verb and resource ('List ... comments') and adds scope ('latest', 'moderation view') that separates it from the read-only siblings list_post_comments and search_comments. It stops short of naming those alternatives explicitly, so differentiation is implied rather than stated.

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?

'Requires admin' gives a genuine precondition, and '(moderation view)' implies the moderation context. However, it never says when to choose this over list_post_comments or search_comments, nor what the moderation framing changes about the result set.

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

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

With no annotations, the description carries the behavioral burden well: it discloses pagination, newest-first ordering, the admin permission requirement, and the non-obvious quirk that attachments come back as storage keys only. It doesn't state rate limits or a strict read-only guarantee, but the disclosed traits are solid.

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, then the filters, then the caveat, then the auth requirement. No wasted words.

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

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

For a read-only paginated list with no output schema and undocumented params, the description covers the key call-shaping facts (filters, ordering, auth, attachment format). Return field detail is omitted but largely unnecessary for a listing tool.

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

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

Schema coverage is 0%, so the description must compensate. It clarifies q (matches reported FQDN or reporter email) and status (filter), and 'paginated' gestures at limit/offset, but limit and offset defaults/bounds are left entirely to the bare schema. Partial compensation only.

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 ('domain abuse reports'), and the paginated/newest-first scope immediately identifies it apart from the mutation sibling admin_domain_abuse_transition. An agent can select 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?

The description explains the filter semantics but never states when to reach for this tool versus admin_domain_abuse_transition or other admin list endpoints. Usage is implied by 'List ... reports' rather than explicitly framed as read-vs-modify 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?

With no annotations, the description carries the full burden; it does disclose the admin authorization requirement and the lifecycle semantics of pending vs. claimed entries, which is genuinely useful. It stops short of confirming read-only behavior (only implied by 'List'), and says nothing about pagination behavior despite limit/offset parameters.

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

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

A single dense sentence leads with the resource, then parenthetically supplies domain context, then the filter list, then the auth note. No filler, front-loaded, and all four clauses earn their place; only slightly long.

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

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

For a read-only listing tool with no output schema and no annotations, the description covers the essentials: what is listed, what the entry states mean, how to filter, and who may call it. Missing only pagination expectations, which the schema's defaults largely handle.

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 40%, and the description compensates partially by mapping status/suffix/keyword to real filters and clarifying that the keyword matches fqdn or a legacy whois email (slightly richer than the schema's 'fqdn / email'). It adds nothing about limit/offset or the 'all' status default, so it does not 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?

The description states a specific verb and resource ('List PFS pre-reserved domains') and even explains the domain-specific concept, including the legacy PublicFreeSuffix origin. However, it never explicitly distinguishes itself from close siblings like admin_list_domain_suffixes or admin_list_domain_registrations, so an agent must infer which listing tool to pick.

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

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

It names the available filters (status / suffix / keyword) and notes the admin requirement, which implies operational context, but there is no explicit when-to-use vs. alternative guidance or any exclusion ('use X instead when...'). The related assignment tools (admin_assign_domain_preallocation) are the natural next step but are never referenced.

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

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

With no annotations, the description carries the burden and does disclose genuinely useful behavior: results are paginated, ordered newest first, and the call requires admin privilege. It falls short of describing return shape or rate/auth-token specifics, so it is not fully transparent.

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

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

A single dense sentence that front-loads the operation, then pagination/order, then parameter meaning, then the admin gate. Efficient, though the semicolon-separated parameter clauses are somewhat packed.

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 paginated admin list tool with no output schema, it covers scope, ordering, parameter semantics, and the privilege requirement. The main omission is any hint at the returned fields or the shape of pagination metadata.

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

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

Schema coverage is only 40%, but the description compensates by explaining that q fuzzy-matches the label in unicode or ASCII or the owner's username, and that status/suffixId are filters. limit/offset are left to the schema's defaults, so a small gap remains.

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 all domain registrations") with scope ("across the platform"), which contrasts with the singular admin_get_domain_registration and the adjacent admin_list_domain_preallocations / admin_list_domain_suffixes. It does not name a sibling explicitly, so it stops short of a 5.

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

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

"Requires admin" gives a prerequisite and "optional status/suffixId filters" implies when to narrow results, but the description never states when to prefer this over admin_get_domain_registration or the other domain-list siblings. Usage is implied rather than directed.

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

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

With no annotations at all, the description carries the full disclosure burden and does meaningfully better than nothing: it states the admin authorization requirement and reveals that the response is an aggregate report (counts, per-suffix reserved-label data, DNSSEC availability) rather than a bare list. It is implicitly read-only via 'List', but does not discuss rate limits, result volume, or ordering.

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

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

One sentence, front-loaded with the resource and its payload, with the auth constraint placed last where it belongs. No filler or repetition of the tool name.

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

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

With no output schema, the description is the only source of return-value information, and it enumerates the three categories of data returned. The auth requirement is also covered. Only result size/ordering and whether the list is exhaustive or paginated are left 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. Schema coverage is also reported at 100%.

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

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

The description names a specific verb and resource (list registration suffixes) and enumerates the exact payload (registration counts, reserved-label aggregates, DNSSEC availability), which cleanly separates it from admin_list_domain_registrations and admin_list_domain_preallocations. It does not, however, explicitly contrast itself with the non-admin domains_suffixes sibling, so the differentiation rests on the admin_ prefix rather than stated text.

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 only usage signal is the trailing 'Requires admin', which is a prerequisite rather than a when-to-use rule. There is no guidance on when to prefer this over domains_suffixes or admin_get_domain_registration. Usage is implied by the name and the prerequisite, but not spelled out.

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

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

With no annotations, the description carries the burden and does disclose real behavioral traits: baseline zh content, newest-first ordering, the shape of per-locale translations, pagination, and the admin requirement. It stops short of stating default page size, totals, or count behavior, which keeps it from a 5.

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

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

A single dense sentence with the resource and key scoping facts front-loaded, using parentheticals and semicolons efficiently. No wasted words, though the stacked clauses make it slightly heavy.

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

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

No output schema exists, and the description usefully sketches the return structure (locale → {title, subtitle, description}) along with ordering and auth. For a two-param read-only list tool this is close to complete, with pagination parameter detail the main 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 0% for both limit and offset, so the description must compensate. It only says "paginated," which hints the params exist but gives no defaults (25/0), ranges (max 100), or semantics for each parameter, leaving the agent to infer from JSON defaults alone.

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 ("List feature intro cards") and adds scope that distinguishes it from siblings like admin_list_feature_switches, admin_upsert_feature_card, and admin_delete_feature_card. An agent can tell this is the read-only enumerator for feature cards 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 precondition "Requires admin" is given, which implies usage context, but there is no explicit when-to-use vs when-not guidance or reference to the sibling upsert/delete feature-card tools. Usage is inferable from the purpose but not spelled out.

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

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

With no annotations, the description carries the full burden, and it does add real behavioral context: it discloses that the operation requires admin rights and that the key set is a strict allowlist mirroring the web admin settings console (i.e., a fixed, complete enumeration rather than an open-ended key space). It does not describe the return shape, though for a zero-parameter read tool that is a minor 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?

Three tight sentences, front-loaded with the action and resource, then the scope enumeration, then the allowlist/permission caveats. Every clause earns its place with no filler.

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

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

With no output schema and no annotations, the description supplies the two things an agent most needs: what the return contains (boolean switch values across a defined category set) and the auth requirement. Only the exact response shape (e.g., a key-to-boolean map) is left implicit, which is a small residual 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?

The tool takes no parameters, so the baseline is 4. The description adds useful semantics about the response content instead — what the switch values represent and which categories they cover — which is the relevant information for a parameterless call.

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

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

States a specific verb ('List') and a precisely scoped resource: the site's boolean feature switches with their current values. The parenthetical enumeration (registration, auth, 2FA, MCP admin tools, etc.) pins down exactly which switches are in scope and implicitly separates it from admin_get_settings and admin_set_feature_switch. It stops short of naming those siblings explicitly, so it falls just below the top mark.

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 prerequisite 'Requires admin' is stated, but there is no explicit when-to-use guidance or routing to alternatives such as admin_get_settings (for non-switch settings) or admin_set_feature_switch (to change a value). Usage is only implied from the description's scope.

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

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

With no annotations, the description carries the full burden and does a good job: it discloses pagination, sort order (newest first), what is joined into results, usage stats, and the admin authorization requirement. It stops short of disclosing rate limits or the exact response shape, but the auth and ordering disclosure are genuinely valuable.

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 dense, front-loaded sentence that puts the core action first and packs the ordering, joins, and parameter guidance after. No filler, though the colon-delimited clauses make it slightly heavy to parse.

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

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

For a read-only admin list tool with no output schema and no annotations, the description covers the essentials an agent needs: scope, ordering, pagination, joined data, stats, filtering, and the admin requirement. Only the explicit meaning of limit/offset is 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 25%, so the description must compensate, and it does for two of the three undocumented parameters: it explains the filter semantics (all | used | unused, default all) and q's fuzzy matching on the code. limit/offset are only gestured at via "paginated", leaving their roles implicit, which keeps this just below top marks.

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 ("List site-wide invite codes") and goes further to name the ordering (newest first), the joined entities (creator and consumer), and the accompanying usage stats. It is clearly distinguishable from admin_revoke_invite, its only nearby sibling on the same resource.

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

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

Usage is implied by "List" and the admin gating, but there is no explicit statement of when to reach for this tool versus alternatives, nor any when-not guidance. Adequate but with a clear gap for a list tool in a crowded admin namespace.

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

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

With no annotations provided, the description carries the behavioral burden and does disclose meaningful traits: case-insensitive matching, newest-first ordering, and the admin authorization requirement. It stops short of covering rate limits, whether soft-deleted keywords appear, or pagination interaction, so it is not fully complete.

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 clauses with the primary operation and filter semantics front-loaded, then the auth precondition. No filler or redundancy.

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

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

For a low-complexity, read-only list tool with three simple params and no output schema, the definition covers filter semantics, ordering, and access control adequately. Paging return shape is the only notable omission and is partly inferable from the schema's limit/offset defaults.

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

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

Schema description coverage is only 33% (q is documented; limit and offset are not), so the description should compensate more. It reinforces q's substring semantics ('case-insensitive', 'omit for all') but adds nothing about limit/offset bounds or paging behavior beyond what the raw schema shows.

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), resource (moderation keyword blacklist), and filtering semantics (word substring, case-insensitive), plus result ordering (newest first). This clearly distinguishes it from the write-side siblings admin_add_keyword, admin_bulk_add_keywords, and admin_delete_keyword.

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 'Requires admin' clause gives an access prerequisite, and substring search over the blacklist is implied by the name. However, it never states when to choose this over related siblings or any exclusion conditions, leaving usage to inference.

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

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

With no annotations, the description carries the full burden and does well: it states read-only semantics, discloses the admin authorization requirement, and details what the payload contains (status buckets, time windows, 50-row cap, per-row recipient/template kind/attempts/last error). It omits pagination/truncation behavior for the counts and any rate or retention caveats, so it is thorough but not exhaustive.

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 resource and read-only flag, then enumerates the returned data in one dense but purposeful sentence. The parentheticals about the ops console and REST-route parity earn their place by explaining scope limits, though the description is on the heavy side for a no-parameter list tool.

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

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

With no output schema and no annotations, the description supplies what an agent needs: safety profile, authorization requirement, return shape, row cap, and the guarantee that the view is non-filterable. Nothing essential for 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?

The tool takes zero parameters, so the schema baseline of 4 applies; there is nothing further for the description to disambiguate. The 'no extra filters' note usefully confirms that absence is intentional rather than an omission.

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

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

Names a specific resource (mail queue / sent-mail log) with a clear verb-equivalent (view) and an explicit scope: status counts over 24h/7d plus the 50 most recent undelivered mails. An agent can distinguish it from the template-and-config siblings such as admin_list_mail_templates 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?

Declares the read-only nature and explicitly warns there are no extra filters, mirroring the fixed console/REST route, which steers the agent away from trying to parameterize it. It does not name an alternative tool or state when another mail-related sibling would be preferable, so it stops short of full when-to-use guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it explains the returned override state, clarifies that 'enabled: false' means the mail channel skips sending, and documents the fallback behavior when override fields are empty. It also states the admin authorization requirement, which is important context for a sensitive endpoint.

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

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

The description is front-loaded with the main action and a colon-delimited list of relevant return fields. It is dense but every clause contributes useful information, though the long enumeration makes it somewhat run-on rather than optimally scannable.

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

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

There is no output schema and no annotations, so the description must explain what the tool returns and its behavioral constraints. It does so by enumerating the returned fields, clarifying bilingual copy ownership, fallback behavior, the meaning of 'enabled', and the admin requirement. This is complete for a parameterless admin list tool.

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

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

This tool has zero input parameters, so the baseline is 4. The description appropriately focuses on returned fields and their semantics rather than input parameters, adding useful meaning beyond the empty input schema.

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

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

The description uses a specific verb ('List') and resource ('mail templates') and details the override state fields returned. It does not explicitly distinguish this list tool from adjacent siblings such as admin_list_mail_log or admin_preview_mail_template, 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?

The description gives no explicit when-to-use guidance or alternatives. It states 'Requires admin,' which is a prerequisite rather than usage guidance, and never explains when to choose this tool over admin_preview_mail_template, admin_set_mail_template, or admin_list_mail_log.

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

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

With no annotations, the description carries the full burden, and it does well: it discloses pagination, newest-first ordering, the record fields, the global storage-stats side output, and the admin requirement. It omits any note on rate limits or read-only guarantees, but for a read-only listing it is substantively transparent.

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

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

Three tightly packed sentences, front-loaded with purpose and scope before filters and side outputs. Every clause conveys information not already obvious from the name.

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

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

No output schema and no annotations, yet the description enumerates returned fields and the aggregate stats, so the agent knows what comes back. Minor gaps remain on pagination defaults and safety framing, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is only 40% (q and userId documented, kind/limit/offset not), so the description must compensate. It explains q's fuzzy-matching target, userId as an owner filter, and enumerates the kind values (inline | avatar | cover | featured), covering the otherwise-undocumented enum parameter.

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 (list site-wide media library items) and adds a scope qualifier ('site-wide') that implicitly separates it from the sibling list_my_media. It also enumerates the returned fields, so an agent knows exactly what this tool produces.

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 prerequisite 'Requires admin' is stated and the filters are described, giving implied usage context. However, it never explicitly says when to choose this over alternatives such as list_my_media or how it relates to admin_delete_media, so routing remains partly inferential.

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

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

With no annotations provided, the description carries the full burden and does add real context: the sort order (priority desc, price asc), the exact fields returned, and the admin authorization requirement. It does not discuss pagination, result size, or whether the catalog can be empty, leaving gaps for a no-annotation tool.

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

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

A single front-loaded sentence leads with the action and resource, then folds in sort order and the field list. The field enumeration is long but earns its place because there is no output schema to carry that 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 zero-parameter read tool with no annotations and no output schema, the description compensates well by naming the authorization requirement and enumerating what is returned plus the sort order. Minor omissions like emptiness/pagination behavior are irrelevant here since no inputs exist.

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

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

The schema has zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The enumerated return fields are helpful but concern output, not input semantics.

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

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

States a specific verb ("List") and resource ("display-name perk catalog"), and its scope is clearly the catalog rather than the subscribers, so it is cleanly distinguishable from the sibling admin_list_perk_subscribers. An agent can tell what it retrieves 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?

"Requires admin" gives a useful prerequisite, but there is no explicit when-to-use, no when-not-to-use, and no named alternative among siblings like admin_list_perk_subscribers or admin_update_perk. Usage is only implied by the listing nature of the 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?

With no annotations, the description carries the full burden and does a solid job: it discloses pagination and sort order ('paginated, newest first'), the auth prerequisite ('Requires admin'), and the shape of returned rows. It does not mention rate limits or total-count/cursor behavior, so not quite exhaustive.

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 layered detail in one dense but coherent sentence plus two short ones. Every clause (search, status filter, pagination, row contents, admin requirement) adds real information with no filler.

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

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

For a paginated admin list tool with no output schema and no annotations, the description covers the essential ground: auth, filtering, pagination, and return fields. It stops short of documenting the limit parameter and any pagination limits, but nothing critical to a correct call is missing.

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

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

Schema coverage is only 20%, so the description must compensate, and it does: it explains q (username/display-name search), the status filter's semantics ('active | expired | revoked; anything else means no filter'), and offset pagination. Only 'limit' (default 25, max 100) is left entirely undocumented in both description and schema.

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

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

States a specific verb and resource (list one perk's subscribers), scoped to a single perk, and is clearly distinguishable from siblings like admin_list_perks (which lists perks) and admin_revoke_perk_subscription (which acts on one subscription). An agent can identify the tool's job 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 context for use: requires admin, is scoped to one perk, and calls out that the returned subscription id is 'needed for revoking', implicitly routing to admin_revoke_perk_subscription. It does not name an explicit alternative or a when-not condition, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden and delivers well: it states the ordering ('newest first'), the exact return fields (id, scope, topicId + topicName, expiresAt as ISO), the scope-conditional field, and the admin auth requirement. Only pagination/bounding behavior is unstated.

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

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

A single front-loaded sentence opens with verb+resource before the parenthetical details, with no filler. It is dense and slightly run-on with two parentheticals, but every clause carries information.

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

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

No output schema exists, and the description correctly fills that gap by enumerating the returned fields, their formats, and the sort order, plus the auth requirement. It is close to complete for a simple read; only cardinality/pagination behavior is missing.

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

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

Schema coverage is 0% for the single parameter, so the description must compensate. 'for one post' clarifies that postId identifies the target post, but it adds no format or constraint detail (the uuid format lives only in the schema), leaving the parameter semantics minimally explained.

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 (site-wide pins) with scope (for one post) and even names the rails involved (latest/hot/topic). An agent can distinguish it immediately from write siblings like admin_set_pin and admin_delete_pin.

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 discloses the access requirement ('Requires admin') and the object of the query, so usage is implied, but it gives no explicit when-to-use guidance or routing to alternatives (e.g., the relationship to admin_set_pin, admin_delete_pin, or pin-listing within admin_list_posts).

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the admin authorization requirement and that the operation is a read/list, but says nothing about pagination behavior, the default 30-item page, or result ordering, leaving meaningful gaps.

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

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

A single compact sentence with the resource and scope front-loaded and no filler. Every clause earns its place.

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

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

For a four-parameter, no-output-schema list tool with no annotations, the description omits pagination semantics and defaults that an agent needs to call it correctly. The status filter and admin requirement are covered, but the definition is only minimally adequate.

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 25% (only 'search' is documented in the schema), so the description should compensate. It adds that posts can be filtered by status, mapping to the enum parameter, but says nothing about limit, offset, or the search field it could have clarified.

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 posts') with explicit scope ('across the platform') and a moderation framing, which distinguishes it from siblings like list_my_posts. It stops short of naming a specific alternative such as search_posts, so sibling differentiation is implied rather than stated.

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?

'Requires admin' gives a prerequisite and '(moderation view)' hints at context, so usage is implied. However, there is no explicit guidance on when to choose this over search_posts, list_my_posts, or admin_list_topics, nor any exclusion 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?

With no annotations provided, the description carries the full burden and does well: it discloses the sort order (newest first), that results are paginated, the auth requirement, and the per-row payload ('applicant identity and current account type'). It omits any rate-limit, total-count, or pagination-metadata behavior, so it is not quite exhaustive.

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 dense sentence plus a short auth clause; the resource and scope are front-loaded and every clause (filters, ordering, row shape, auth) earns its place with no filler.

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

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

With no output schema, the description does describe the return rows and the ordering, and it covers all filters and the admin gate. It lacks detail on pagination metadata (totals, next-page signals) and on what happens when no applications match.

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

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

Schema description coverage is only 25%, so the description must compensate and largely does: it maps the status enum to a filter, explains q as fuzzy-matching username or display name, and signals pagination. It never names or explains limit/offset defaults or the 100 max, which schema picks up only structurally.

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 ('List professional-account applications') plus the console context, ordering ('newest first'), and pagination. An agent can tell this apart from the decision counterpart admin_decide_pro_application and from admin_list_verifications 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 use ('for the review console') and states the access prerequisite ('Requires admin'). It does not explicitly name an alternative or state when not to use it, so it stops short of the when/when-not/alternatives bar.

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

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

With no annotations provided, the description carries the full burden and largely succeeds: it discloses read-only/no-side-effects, admin requirement, ~14-day pg-boss retention, newest-first ordering, and that invalid state values are ignored. It stops short of describing pagination or the response shape in detail.

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

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

Three dense sentences, front-loaded with the core purpose and followed by filters and constraints. No filler, though the parenthetical list of subsystem ledgers is somewhat list-heavy.

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

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

For a read-only list tool with no output schema, the description explains what comes back (filtered total, distinct names, cron schedules, ledgers) and covers safety and retention. The main gap is the undocumented limit/offset paging 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 50%: name and state are described, but limit and offset have no schema description and are not mentioned in the description either, leaving the pagination parameters undocumented anywhere. The description's state/name notes largely restate the schema, so added value is modest.

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 pg-boss jobs') and adds scope detail: newest-first ordering, filtered total, distinct job names, plus cron schedules and subsystem ledgers. This clearly separates it from siblings like admin_delete_queue_job and admin_retry_queue_job.

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 describes the optional filters and read-only nature, which implies it's the inspection tool, but never explicitly routes the agent to alternatives such as admin_delete_queue_job or admin_retry_queue_job, nor states when-not to use it. Usage is implied rather than spelled out.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the admin authorization requirement and the default filter behavior, but says nothing about whether it is read-only, pagination/return behavior, or what a report record contains.

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

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

Extremely tight and front-loaded: the core action, the default filter, and the auth prerequisite all appear in one short sentence with zero filler. Brevity comes at some cost to completeness, but structurally it is well formed.

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

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

For a two-parameter, no-output-schema, no-annotation admin list tool, the description covers the essentials (action, default scope, auth) but leaves the limit parameter, the enumeration of statuses, and the shape/paging of results unaddressed. Adequate but with visible gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the status parameter's default and filter role, but omits the valid status values and says nothing at all about the limit parameter (default 30, max 100), leaving that parameter's semantics to the raw schema alone.

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 clear verb+resource ('List reports') plus the default scoping and that it is admin-only, which distinguishes it from action siblings like admin_resolve_report or admin_report_action. It does not explicitly name those siblings, so differentiation is implied rather than stated.

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

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

Provides an implied context (admin-only, defaults to open reports) but gives no explicit when-to-use versus the related tools admin_resolve_report/admin_report_action, nor when to set status='all' versus a specific status. Usage is inferable but not spelled out.

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

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

No annotations exist, so the description carries the full burden. It discloses the auth requirement ('Requires admin') and describes the returned data (governance fields plus heat metrics), which is useful. However it never states read-only semantics, pagination behavior, or result ordering despite limit/offset/sort parameters.

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

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

A single tightly packed sentence with semicolon-separated clauses that front-loads the resource and its returned fields before the operations and prerequisite. No filler, though the density makes the sort/enum mapping less than obvious.

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

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

With no output schema and no annotations, the description does a fair job covering return content and authorization, but leaves pagination defaults/limits, ordering semantics, and read-only safety unstated for a 5-parameter admin listing tool. Adequate but with clear gaps.

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

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

Schema coverage is only 40%, so the description must compensate. It documents the intent of 'q' (search by name) and 'status' (filter by status), and its parenthetical '30-day post count, subscribers' implicitly maps to the heat/posts/subs sort enum values. It says nothing about limit/offset, leaving pagination parameters undocumented in both places.

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

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

States a specific verb+resource (list topics) and goes beyond tautology by naming what it returns (governance fields, 30-day post count, subscribers) and the two supported operations (name search, status filter). It doesn't explicitly contrast with near siblings like admin_get_topic or admin_list_posts, so an agent must infer the distinction.

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

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

Usage is implied by 'search by name, filter by status' and the prerequisite 'Requires admin', but there is no explicit when-to-use vs. when-to-use-something-else guidance and no named alternatives. An agent can infer it lists topics for admin auditing but gets no routing help.

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

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

With no annotations, the description carries the full burden; it does disclose the admin auth requirement and the returned profile fields, which is meaningful. It says nothing about pagination (the limit cap of 100 with default 30) or result ordering, so key operational behavior is left undisclosed.

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 core action front-loaded and the qualifier trailing. The parenthetical field list is compact and earns its place; nothing is redundant.

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

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

For a simple two-parameter list tool with no output schema and no annotations, the description covers action, scope, returned fields and the admin gate. The gap is pagination/limit behavior, which is minor but non-trivial for a listing endpoint.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that the search string matches username/display name, adding real meaning; the limit parameter is documented nowhere, leaving pagination semantics entirely unexplained.

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

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

States a specific verb and resource (search users) and enumerates the payload (status, role, ban info), so the agent knows what it gets. It does not name the sibling it differs from (search_users), relying on the 'Requires admin' qualifier to signal the distinction.

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

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

'Requires admin' gives a prerequisite, which is useful context for an admin-only surface. However it never states when to prefer this over the sibling search_users or what scope/conditions apply, leaving the agent to infer the alternative.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses default sort order (newest first), pagination, the row payload (applicant identity + current badge), and the admin authorization requirement. It omits rate limits, whether a total count is returned, and what happens with an invalid status value.

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

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

Front-loaded with the verb+resource, then filters, then row contents, then the auth requirement — a sensible information order with no filler sentences. Slightly dense in the middle but every clause carries 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 4-parameter, no-annotation, no-output-schema list tool, the description covers purpose, filtering, ordering, and the essential return shape (applicant identity + current badge). The main residual gaps are pagination bounds/defaults and any total-count 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 only 25%, so the description must compensate. It does clarify that q fuzzy-matches username, display name or label, and that status filters to the three states (already enumerated in the schema), but limit (max 100, default 25) and offset are only gestured at with 'paginated' and remain undocumented anywhere.

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 ('List verification (V badge) requests') with clearly bounded scope (review console, paginated, newest first). An agent can distinguish it from admin_list_badges (badge catalog) and admin_decide_verification (act on a single request) without opening any schema.

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

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

The phrase 'for the review console' and the status filter imply the browse-before-deciding workflow, and 'Requires admin' gives a precondition. However, it never states when to use this versus admin_decide_verification or other list siblings, nor any exclusion criteria, leaving usage to inference.

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

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

With no annotations, the description carries the full burden and covers a lot: declares 'Read-only', states 'Requires admin', and adds the non-obvious trait that disabled templates are still previewable. It also explains the saved-override-vs-draft resolution rule. It stops short of mentioning rate limits or any side effects, so it is strong but not exhaustive.

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?

Effectively one dense paragraph that is front-loaded with what the tool does and the returned fields. Every clause carries information, but the run-on packing of draft-vs-override and locale semantics reduces scannability slightly.

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

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

For a 7-parameter tool with a nested object, two enums, and no output schema, the description compensates well by listing return fields and the override/draft rules. It is complete enough to invoke correctly, though nothing is said about error behavior for an invalid key.

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 86% (baseline 3), and the description adds genuine meaning beyond the schema: locale selects the rendering side and reflects mono-lingual per-recipient delivery, and data overrides individual sample variables while the four draft fields bypass the saved override. This clarifies the interaction between parameters rather than repeating field docs.

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 (Preview) and resource (one mail template rendered with sample values), and even enumerates the return shape {subject, text, html}. An agent can distinguish this from admin_list_mail_templates, admin_set_mail_template, and admin_reset_mail_template 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?

Explains the primary use case clearly ('so edits can be previewed without saving') and notes the edge case that disabled templates can still be previewed. It implies the preview-vs-save split against set_mail_template but never names an alternative sibling or states an explicit when-not to use it.

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

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

With no annotations, the description carries the full burden and does disclose key side effects: the author is notified and the content is hidden, plus the admin permission requirement. It omits reversibility (can the rejection be undone?), what happens to existing comments/media on the post, and error behavior.

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

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

A single sentence with the action and effect front-loaded and no filler; every clause (reason, author notified, content hidden, requires admin) carries 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 two-param mutation with no annotations and no output schema, the description covers the action, the state, the permission, and the immediate effects, but leaves reversibility and downstream effects on related content unexplained.

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

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

Schema description coverage is 0%, so the description must compensate and only partly does: 'a post' maps loosely to postId and 'with a reason' to reason, but the uuid format, the 500-char limit, and whether the reason is shown to the author are left to the schema.

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

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

The description gives a specific verb+resource pair ('Reject a post') and constrains the state to 'pending review', which implicitly separates it from the sibling admin_approve_post. It does not explicitly name that sibling, so it stops short of a 5.

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

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

'post pending review' tells the agent the applicable state and 'Requires admin' states a precondition, but there is no explicit when-not guidance or named alternative (e.g. use admin_approve_post to accept instead). Usage is implied rather than spelled out.

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

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

With no annotations, the description carries the full burden and does disclose two genuinely useful traits: the admin authorization requirement and the partial-ordering semantics ("boards left out keep their current order"), which is the key behavioral subtlety for this mutation. It stops short of covering atomicity, invalid-id handling, or reversibility.

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

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

A single front-loaded sentence with the parenthetical detail placed after the main action. No waste, though the parenthetical wraps two ideas (completeness and omission behavior) that could be stated more cleanly.

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

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

For a one-parameter mutation with no annotations and no output schema, the description covers the action, the auth gate, and the ordering semantics. Remaining gaps (failure behavior, whether the reorder is atomic) are minor against the tool's low complexity.

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

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

Schema coverage is 0% (only type/array/min-max items), so the description must compensate, and it does: it explains orderedIds is the full intended order and that omitted boards retain their current position. The phrasing "must list every board id" sits awkwardly against "boards left out keep their current order," which slightly muddies the intended constraint.

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: saving the board display order. That is clearly distinct from admin_upsert_board (create/update a board) and admin_list_boards (read), so an agent can route correctly even though no sibling is named explicitly.

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

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

"Requires admin" gives a precondition, and reordering boards is implied to be an admin maintenance task, but there is no explicit when-to-use vs alternatives guidance (e.g., versus admin_upsert_board, or when partial reordering is preferable). Adequate but thin.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses that every branch closes the report and notifies the reporter, that content/author side effects are applied through the same path as the web workbench, that delete_content is a soft-remove, and that permanent/staff bans are admin-only. Return shape and exact notification semantics remain unspecified, but the mutation and permission profile is clearly conveyed.

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 plus a short closing requirement is front-loaded with the action list and wastes little, though the nested parentheticals make it slightly harder to scan than a bulleted branch list would be. Every clause carries 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 multi-branch mutation tool with no annotations and no output schema, the description covers the action set, side effects, reporter notification, soft-delete behavior, and admin-only constraints. An agent can invoke it correctly; only the response/return contract is 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 67%, so the schema already documents most parameters (note, reason, banDays bounds, message). The description usefully ties parameters to their branches (banDays omission means permanent, reason is mandatory for ban_author) but largely restates the schema's own descriptions rather than adding new meaning.

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

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

The description names a specific verb-plus-resource ('Report-workbench quick action') and enumerates all five branches with a short gloss for each, so an agent knows exactly what selecting this tool does. It does not, however, contrast itself with overlapping siblings such as admin_resolve_report or admin_delete_comment, which is the only thing keeping it from a 5.

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

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

Usage is implied through the per-branch semantics (ban_author, warn_author, delete_content), and the 'Requires admin' plus 'permanent/staff bans are admin-only' constraints give some selection guidance. But there is no explicit when-to-use-this-versus-sibling routing given the many overlapping admin_* report/user/comment tools in the same namespace.

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

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

With no annotations, the description carries the full burden and does well: it discloses the destructive side effect (override row removed), an unexpected state change (enabled resets to true), the return value ({ ok: true }), and the authorization requirement (Requires admin). It stops short of saying the dropped customizations are unrecoverable or noting any audit implications.

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 front-loaded sentences with no filler: effect, then side effect, then return value and auth requirement. Every clause earns its place.

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

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

For a one-parameter admin mutation with no output schema, the description supplies the missing pieces an agent needs: the mutation's effect, the reset side effect, the response shape, and the privilege requirement. Nothing material 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 100% with a fully enumerated key list, so the schema already carries parameter meaning. The description only says 'one mail template' and adds no guidance on the enum values (e.g. what 'test' or 'system' mean), so the baseline 3 applies.

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

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

States a specific verb-and-resource pair — 'drop the saved override for one mail template' — and adds the resulting effect (restore built-in copy). This is clearly distinguishable from the neighbouring admin_set_mail_template (which writes an override) and admin_preview_mail_template (which renders one).

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 scenario is implied by 'drop the saved override ... restore the built-in bilingual copy', which tells an agent this is the revert path, but no sibling is named and no explicit when/when-not condition is stated. Adequate but leaves 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?

With no annotations, the description carries the full burden and does disclose the key traits: it is a status mutation, it writes an audit log entry, it does not take down content, and it requires admin privileges. It omits reversibility/idempotency and whether re-resolving an already-closed report is allowed, which are meaningful gaps for a mutation.

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

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

A single front-loaded sentence with a parenthetical that pays for itself by ruling out content takedown. No filler, no repetition of the tool name, and the authorization caveat lands last where it belongs.

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

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

For a mutation tool with no annotations and no output schema, the description covers scope, side effects, and auth, but leaves parameter meanings (reportId, note) and post-call behavior unexplained. Adequate but with clear gaps an agent would have to guess at.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It only implicitly covers 'outcome' via the words resolved/dismissed (matching the enum), and says nothing about 'reportId' or the 'note' parameter's purpose or 500-character limit.

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 (mark resolved/dismissed) and resource (report), and the parenthetical clarifies the effect is a status update plus audit log rather than content removal. It does not explicitly distinguish itself from the sibling mod_resolve_report or admin_report_action, so an agent must infer which tier applies.

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

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

Gives positive conditions (marking a report resolved or dismissed) and a useful negative boundary: content takedown is not handled here and still requires the web console. 'Requires admin' sets the permission prerequisite. It stops short of naming alternative tools for related report actions.

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

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

With no annotations, the description carries the full burden and does so thoroughly: retry budget (retryLimit/retryDelay/backoff) is preserved, a future startAfter keeps its delay, the payload carries over, the old record is deleted irreversibly, and the action is audit-logged and admin-gated. This discloses exactly the destructive and permission characteristics 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?

Front-loaded with the verb and resource, and the dense parenthetical clauses each carry distinct information (retry budget, startAfter, payload). It is long for a two-parameter tool but nearly every clause earns its place; only minor tightening is possible.

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

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

For a mutation tool with no annotations and no output schema, the description covers mechanics, reversibility, preserved state, error behavior, and auth requirements. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so both parameters are already documented (uuid id, queue name). The description only restates that both are required and adds the 404 condition, which is behavioral rather than parameter meaning, so baseline 3 applies.

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

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

States a specific verb+resource (retry a pg-boss job) and immediately distinguishes itself from the sibling admin_delete_queue_job by clarifying that deletion is a side effect of re-enqueueing, not the goal. An agent can tell this apart from list/delete queue tools 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 clear operating context: requires the job's queue name and id, returns 404 if no such job, and requires admin. It does not explicitly name alternatives (e.g. admin_delete_queue_job for outright removal), so it stops short of full when-not guidance.

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

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

With no annotations, the description carries the full burden, and it usefully discloses two behavioral traits: a 404 error when no grant record exists, and an admin authorization requirement. It omits reversibility (whether the grant can be restored via admin_grant_badge) and any success-side effect, which keeps it below 5.

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

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

Three compact clauses, front-loaded with the action and scope, then inputs, then error and auth behavior. No filler sentences; every clause earns its place.

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

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

For a two-param mutation with no output schema and no annotations, the description covers purpose, both inputs, the error case, and the auth requirement. It leaves the return value and reversibility unstated, a minor gap given no 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 only 50% (badgeId has no schema description), and the description compensates by clarifying that userId is the grantee's id — a semantic distinction the schema's 'grantee user id' only partly conveys — and noting both are uuids. It adds meaning beyond the raw 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?

Specific verb (revoke) plus resource (badge grant) plus scope (one user's), which cleanly separates it from the sibling admin_grant_badge. An agent knows exactly what operation this performs 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 tells the agent how to source the inputs (see admin_list_badges grant counts or the badge admin page) and states the admin prerequisite, giving clear usage context. It stops short of an explicit when-not or naming the re-grant counterpart as the inverse operation, so it is not a full 5.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the destructive nature (delete), the precondition that only unused invites qualify, that used invites return 404, that the removal is audit-logged, and that admin privileges are required. It omits reversibility, but for a delete on an unused invite the disclosed traits are substantial.

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