RedM Mcp

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

Goes well beyond the readOnly/destructive annotations: 15-minute download link lifetime, 24-hour job expiry, pre-conversion upload-link refresh, and explicit security constraints (untrusted file/clip names, do not publish transfer URLs/tokens, no automatic install claims). The description carries far more behavioral context than the annotations supply.

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 access prerequisite and job scope, then layers behavior and safety. Dense and efficient, though the run of security caveats could be tightened 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?

Given a single-parameter tool with an output schema, the description supplies the missing access, expiry, and safety context an agent needs. Nothing essential to correct invocation is absent, and it does not waste space re-explaining return values the output schema already covers.

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 the single jobId parameter, so the description must compensate. 'Read your own job' implies ownership scoping and job expiry, which adds meaning, but it never clarifies jobId format or provenance. Marginal value over 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?

Specific verb+resource: reads the status of an animation conversion job and describes exactly what it returns (ZIP link, SHA-256, YCD paths, dictionary/clip mapping, warnings, integration instructions). Clear scope ('read your own job') that separates it from the create/start 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?

States the prerequisite ('Requires animation conversion access') and the timing context ('When succeeded/partial', 'Before conversion it refreshes pending upload links'). It does not explicitly name alternative tools or when not to use it, 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?

Adds substantial behavior beyond the annotations: chunked upload mechanics (consecutive raw 512 KiB chunks with returned PUT URLs), retention of uploads/results in the admin animation library, idempotent retry guidance via requestId reuse, and the fact that there is no automatic installation. These are exactly the operational facts annotations cannot convey.

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

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

Front-loads access requirement and purpose, then workflow, then limits. Dense and largely waste-free, though several constraint clauses are packed into long sentences, making it slightly harder to scan than an ideal definition.

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

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

For a complex 8-parameter upload tool with an output schema, the description covers access, formats, destination resolution, upload protocol, limits (8 files, 32 MiB each, 64 MiB total, 32 clips), accepted inputs, and the absence of auto-installation. 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?

With 75% schema coverage already, the description still adds real meaning: targetResource's effect on the output bundle, resourceName as a reusable package label not a runtime resource, requestId reuse for retries, and client-side size/SHA-256 computation. It does not explain fingerPose/rootMotion behavior beyond what the schema descriptions already state, so it is not a full 5.

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

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

States a specific verb and resource (upload/convert animations for RedM conversion) and names the input formats (FiveM YCD, Mixamo FBX). It also names the follow-up sibling admin_start_animation_conversion, so the agent can place it in the workflow without opening other schemas.

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

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

Gives explicit prerequisites (requires animation conversion access; RedM only), an explicit ordering instruction (first establish the destination, then call admin_start_animation_conversion), and a decision rule for targetResource (set it for asset-only bundle, omit for standalone preview). Alternatives are named rather than implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description goes well beyond them: cascade deletion of native links, rewriting/clearing the quoted finding_context on those natives, immediate disappearance from lookup_native and semantic_search, a stated up-to-10-minute semantic_search cache lag, and explicit irreversibility. This is precisely the extra context a destructive tool needs.

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

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

Three dense sentences, front-loaded with the access scope and irreversibility, then side effects, then the alternatives. Every clause adds operational information; nothing is boilerplate or restated from the title.

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

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

For a destructive, no-output-schema admin tool this is complete: it covers scope of deletion, cascading side effects, cache behavior, irreversibility, prerequisites and the preferred sibling alternative. Nothing an agent needs before invoking is missing.

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

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

There is a single parameter with 0% schema description coverage, so the description must carry the meaning of `id`. It implies the value is a finding identifier but never states that explicitly (as opposed to a native id or game id), so it only partially compensates for the coverage gap. Adequate but not compensating.

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?

'Admin-only: permanently delete a community finding' gives a specific verb+resource+access scope, and the second sentence enumerates the exact collateral effects (native links, finding_context blurb). An agent can distinguish it from admin_update_finding, admin_get_finding and share_finding 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?

Explicitly routes the agent: 'inspect with admin_get_finding first' and 'prefer admin_update_finding when the finding is merely wrong rather than junk'. It also states a hard precondition ('Only findings of THIS deployment's game can be deleted'), which is exactly the when-not guidance most destructive tools omit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real behavioral context beyond that — admin-only scope, that findings predating IP capture surface as authorIp: null, and that the query spans both games because the DB is shared. It does not mention result size or default limit behavior, but the added edge-case and scope disclosure is strong.

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 output shape before the usage cases and parameter notes; every clause carries information (fields, ordering, alternatives, edge case, cross-game scope). It is dense and slightly long as a single block, but there is no filler to cut.

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

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

There is no output schema, so the description correctly describes the returned fields, the sort order, the cross-game scope, and the null-IP edge case. An agent has everything needed to select and call it, including how it chains into the row-level sibling tools.

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

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

Schema coverage is 0%, so the description must carry the load, and it explains two of three parameters: sinceDays 'counts only recent submissions' and authorIp 'returns that one author'. The limit parameter is left to the schema, though 'ordered by volume' gives implicit context for why a limit matters. Slight gap prevents 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 ('community findings grouped per author IP') and enumerates the exact per-row output fields (count, first/last submission, games, categories, tags, latest title) plus the ordering ('by volume'). This is immediately distinguishable from the sibling admin_list_findings and admin_search_findings, which return individual rows rather than an aggregate.

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 three concrete when-to-use cases ('spot a contributor flooding the corpus', 'find the IP behind a batch of bad findings') and an explicit workflow role: it is 'the entry point before admin_list_findings({ authorIp }) / admin_search_findings({ authorIp })'. The relationship to the alternatives is spelled out, not implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds the 'admin-only' auth gating plus an enumeration of what is returned (author IP, scanner reviewFlags, linked natives, counts), which is meaningful context the annotations do not provide.

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

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

Two tight sentences, no filler. The gating constraint and return contents lead, and the workflow routing follows, making it well front-loaded.

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

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

With no output schema, the description compensates by enumerating the response fields; with only one trivial parameter and annotations covering safety, 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?

One parameter at 0% schema description coverage, so the description must carry meaning; 'by id' plus the workflow hint that ids come from admin_list_findings/admin_search_findings tells the agent where to source the identifier. It does not add format detail beyond the integer type, but that is a minor gap for a single-key lookup.

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 (finding) and enumerates the returned fields, so it is clearly distinguishable from admin_list_findings / admin_search_findings. An agent knows exactly what this retrieves 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 positions the tool in a workflow: use it after admin_list_findings/admin_search_findings and before admin_update_finding/admin_delete_finding. Both the when and the alternative siblings are named.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds valuable context beyond that: default/max limit values, ordering (newest first), returned fields, cross-game span indicated per row, and the presence of reviewStatus/reviewFlags per row. Doesn't cover pagination beyond limit or error behavior, so not a 5.

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

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

Front-loaded with the admin-only scope and return shape, then parameter guidance, then sibling routing. Dense but every sentence carries information; slightly long with nested parenthetical examples, but no wasted 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?

Complete for a filtered list tool with no output schema: return fields are enumerated, filter semantics defined, pagination limit stated, cross-game behavior covered, and follow-up tools named. Nothing an agent needs to call 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 25%, so the description must compensate, and it does: it defines search as case-insensitive substring on title+body, tag as exact match in tags[], authorIp as exact matching with pointer to admin_finding_authors, reviewStatus pending meaning the queue, sinceHours for recency, and limit default/max. This adds meaning well beyond the bare schema properties.

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 (community findings/learnings) with scope (admin-only, both games, newest first) and explicitly names the sibling it differs from (admin_search_findings for relevance-ranked search). An agent can distinguish it from admin_search_findings without opening schemas.

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

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

Explicit guidance on when to use each filter, names the alternative (admin_search_findings) for relevance-ranked search, points to admin_finding_authors to obtain authorIp values, describes the pending review queue workflow, and lists companion tools for drilling in and acting. Nothing is left to inference.

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

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

Annotations already establish readOnly/non-destructive/non-openWorld, so the description does not need to restate safety. It adds meaningful behavior beyond that: admin gating, per-metric window binding, and the game-scoping rule that pre-cutover (game IS NULL) rows are excluded except for metrics marked (cross-game).

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

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

Front-loads the core action and access restriction, then layers the window parameters and the game-scoping caveat in order of relevance. Dense but every clause carries information; 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?

For a tool exposing 65+ heterogeneous metrics with no output schema, the description supplies the scoping, defaults, and cross-game exceptions an agent needs to call it correctly, while delegating per-metric shape to the schema enum description. Return format is not described but is inherently metric-specific and impractical to enumerate here.

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

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

Schema coverage is only 33% — days and sinceHours have no schema descriptions — so the description must compensate. It does: it supplies the defaults (168h/7d and 14d) and the binding rule (sinceHours only for sinceHours-bound metrics, days only for days-bound), which are absent from the schema. It omits the min/max bounds (days ≤ 90, sinceHours ≤ 2160).

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

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

States a specific verb and resource: 'read one named RedM/RDR3 telemetry metric', and notes the backing store (postgres view or core query). It is clearly distinguishable from unrelated siblings like share_finding or asset_lookup, though it never explicitly contrasts itself with the close sibling admin_telemetry.

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 real access precondition ('Admin-only') and tells the agent to select the metric via the `metric` parameter, whose description enumerates every option. However, it offers no guidance on when to prefer this over the obvious sibling admin_telemetry, so tool-level selection is left to inference.

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

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

Goes beyond the annotations (which only declare read-only/non-destructive) by disclosing admin-only access, that argument payloads are redacted, the game scoping to `redm`, and the result cap. It does not state retention window or pagination behavior for retrieving older calls.

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 admin-only scope and the returned fields, then the filters, then the limit and the intended use. Dense but every clause carries information; slightly crammed into three 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 fields, and it covers auth requirement, scope, and all filters. Adequate for an admin read tool; only the missing sibling differentiation and pagination semantics keep it from being fully complete.

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

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

Schema coverage is 0%, so the description carries the load and does cover all four params: `discordId` and `tool` as filters, `ok=false` for failures only, and `limit` with its default of 30 and max of 200. It adds real semantics the bare schema lacks, though it doesn't explain the discordId format expectation.

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 (recent tool calls) with its full returned shape (redacted args, duration, IP, Discord ID/username, OAuth client ID, outcome) and the scope constraint (only the `redm` game). It does not differentiate itself from the close sibling `admin_tool_errors` or `admin_telemetry`, so an agent must infer which one 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?

Explicitly states when to reach for it: 'Use to debug a specific tool or inspect one Discord user's calls.' That maps the two filter params to two intents. It gives no when-not guidance and never mentions the overlapping `admin_tool_errors` sibling, so exclusions are absent.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, not open-world), and the description adds substantial non-obvious behavior on top: no search-cache reads/writes, rerank usage not recorded, bounded maxCases/timeoutSec with defaults and ceilings, synchronous execution, and a one-run-per-pod concurrency limit.

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?

Purpose is front-loaded and every sentence carries operational detail rather than filler. It is dense and the 'Sets:' breakdown is long, but that density is justified by a 6-parameter analytics tool with no schema descriptions.

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 fully specifies the return shape: per-set case counts (available/users/scored/timedOut), MRR/@1/@3/@5/inLimit for both the reranked order and the pre-rerank fused pool, plus the opt-in case detail list. It also warns that ranks are chunk-level, not file-level, preventing a common misread.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely succeeds: it defines both `sets` labels precisely (follow_through and reformulation windows, matching rules, label selection), pins `variant` to `baseline` today, and gives defaults/limits for `maxCases`, `timeoutSec`, and `includeCases`. Only `days` is never mentioned, leaving one parameter 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: replay logged `semantic_search` traffic and score it, scoped to an endpoint's game (`redm`). It is clearly distinct from the sibling `semantic_search` (which serves live queries) and from `admin_metric`/`admin_telemetry`, so an agent can disambiguate without inspecting 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 strong context for when this applies: admin-only, only hybrid-mode searches replayed, one run per pod at a time, admin identities and probe noise excluded. It doesn't explicitly name an alternative tool or say when *not* to use it, which keeps it just short of a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description adds the non-obvious operational details: the retrieval pipeline (vector + Postgres FTS fused via RRF, reranked), the extra admin fields returned (id, authorIp, createdAt, linkedNatives), limit default/max, and that results are scoped to this deployment's game. It does not discuss pagination beyond limit or ranking caveats, so it stops just 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?

Front-loads the core purpose and pipeline before the use cases and filters, and every clause carries information. It is dense and somewhat long for a search tool, but no sentence is filler; it could be trimmed modestly.

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 usefully enumerates the returned admin fields and states the deployment scoping and limit bounds, which is what an agent needs to interpret results. The one gap is the unexplained `mode` parameter, which prevents a full 5.

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

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

Schema description coverage is 0%, so the description must carry the params. It explains `query` (natural-language or token), `authorIp` (exact) and `tag` (exact) post-filters, and `limit` (default 10, max 25). However the `mode` enum (hybrid/semantic/lexical) is never mentioned — the description only describes the default hybrid behavior, leaving the single enumerated parameter undocumented.

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

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

States a precise verb+resource ('rank community findings against a ... query') and immediately contrasts itself with two siblings: it uses the same hybrid retrieval as `semantic_search`, while `admin_list_findings` is a 'plain ILIKE filter; this is relevance-ranked.' An agent can distinguish this from every other search/list sibling without reading schemas.

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

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

Gives three concrete triggers ('find the finding an agent is complaining about', 'spot near-duplicates before editing/merging', 'audit what a query surfaces') and explicitly names the alternative tool plus the condition that separates them (relevance-ranked vs. ILIKE). This is explicit when/when-not/alternative guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the idempotence sentence is partly redundant, but the description adds genuinely new behavioral context: the call returns immediately (async), the polling rate limit of 5 seconds, and the crucial caveat that success means offline validation only, not in-game visual approval. That last point prevents a real misinterpretation.

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 carries distinct information — access requirement, precondition, idempotence, async behavior, polling rate, success semantics — with no filler. The ordering puts prerequisites before the purpose statement, so the tool's identity is not front-loaded, which costs a point.

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

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

An output schema exists, so return-value description is unnecessary, and the description covers access, prerequisites, async/polling behavior, idempotence and success semantics well. The one omission is provenance of jobId (where the agent gets it), which for a one-required-parameter start tool is a meaningful 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% and the single jobId parameter is never mentioned in the description. Given the surrounding tools (admin_create_animation_conversion, uploads), it is likely the agent must obtain jobId from an earlier step, and the description does not say so. With one undocumented parameter and no compensating text, this is below the baseline.

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

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

Names a specific verb+resource ('Start RedM animation conversion', 'Packages RedM YCDs with optional standalone preview scripts') and is clearly distinguishable from the sibling admin_animation_conversion_status and admin_create_animation_conversion. It does not open with the action statement, so the purpose has to be inferred from the packaging clause, keeping it 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?

Explicit gating ('Requires animation conversion access'), explicit timing ('Start after every upload succeeded'), and an explicit alternative with a cadence for the follow-up call ('poll admin_animation_conversion_status no more often than every 5 seconds'). An agent knows exactly when to call this and what to call next.

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

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

Goes well beyond the read-only annotations: it discloses the admin-only authorization gate, the implicit data scope (this endpoint's game, `redm`), and a non-obvious exclusion rule (calls with game IS NULL, pre-multi-game cutover, are dropped). These are behavioral facts the agent could not infer from annotations or schema.

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

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

Front-loads the core purpose, then scoping/cutover caveats, then the routing advice. Three dense sentences with no filler; every clause carries actionable information.

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

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

With no output schema and only two optional parameters, the description covers all the caller needs: what is returned, the default window, the optional filter, the auth requirement, and the data-scope exclusion. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it gives the `sinceHours` default (168 = 7d) and explains that `tool` narrows results to a single tool. It does not specify the expected string format for `tool` (e.g. exact tool name), leaving a minor 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 ('per-tool health snapshot') and enumerates exactly what it returns: calls, errors, error %, p50/p95/p99 latency, unique IPs/sessions. It clearly distinguishes itself from sibling tools like admin_tool_errors, admin_recent_tool_calls and admin_metric.

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

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

Explicitly states when to use it ('to spot tools that are slow, failing, or unused') and names the follow-up alternatives ('before drilling in with admin_tool_errors / admin_recent_tool_calls'), routing the agent the way siblings should be 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?

Beyond the readOnly/openWorld/destructive annotations, the description discloses that access is admin-only, that only thrown exceptions are counted (logical errText results are excluded), and that rows with game IS NULL are dropped. Those are meaningful scope and auth constraints. It still says nothing about pagination, row limits, or ordering of results.

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

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

Purpose is front-loaded before the qualifying parentheticals, and each clause (view parity, exception-only counting, game scoping) adds distinct information. It is dense to the point of being run-on, but nothing is wasted.

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

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

With no output schema, the description usefully sketches the return shape (grouped counts plus latest_message/last_seen) and the filtering invariants. However, the two input parameters remain undefined in both schema and description, leaving an agent guessing about time-window defaults and filtering behavior.

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

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

Schema description coverage is 0% across two parameters, so the description carries the full burden — and it explains neither the `tool` filter nor the `sinceHours` time window (or its default and 2160-hour cap). The mention of errorName grouping does not map to a declared 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?

The description names a specific operation (aggregate tool failures), the grouping key (errorName), the returned fields (latest_message, last_seen), and the data source (the v_tool_errors view). An agent can tell this apart from admin_recent_tool_calls or admin_metric 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?

"Use to triage what's actually breaking before grepping container logs" gives a concrete when-to-use and implicitly positions it against a manual alternative. It does not name a sibling tool to prefer in other cases, so it stops short of full alternative routing.

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

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

Annotations mark it non-read-only, idempotent, non-destructive, but the description goes well beyond: title/body edits trigger re-embedding, body edits re-derive auto-linked natives while preserving explicit links, reviewStatus transitions publish/hide findings, and semantic_search results can lag up to 10 minutes while review changes are immediate.

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?

It is a dense single paragraph, front-loaded with the admin-only directive and patch instructions, and nearly every clause carries operational value. Slightly long, but not 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 complex mutation with no output schema and multiple side effects, the description covers side effects, timing/caching, cross-game refusal, and the read-first workflow — everything an agent needs to call 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 43%, and the description compensates well by explaining replace-whole-list for tags, null-clears for category/source, reviewStatus publish/hide semantics, and full-body-replacement for body. It adds little for title beyond the schema's constraints, 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?

The description opens with a specific verb+resource+scope: 'Admin-only: edit an existing community finding in place.' It clearly distinguishes itself from siblings like admin_create_finding, admin_delete_finding, and admin_get_finding by naming the in-place edit and the read-first sibling.

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

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

It states the workflow explicitly ('Read the current text with admin_get_finding first and send the full corrected body, not a diff'), the patch semantics (pass only fields to change), and an exclusion ('Only findings of THIS deployment's game can be edited'). When-to-use, how-to-use, and a constraint are all covered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds the non-obvious behavioral facts: it is admin-only, visible only to clients holding the `admin` scope, and it reflects the caller's identity and grants rather than arbitrary 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?

Three short sentences, front-loaded with the access restriction ('Admin-only diagnostic'), then the return payload, then the intended use. No filler or repetition of the title.

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

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

With zero parameters, no output schema, and annotations covering the safety profile, the description supplies the remaining essentials: what it returns, who may call it, and why. Nothing an agent needs before invoking it is missing.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-param tool applies. The description does clarify what the parameterless call returns (client id and granted scopes), which is the only semantic gap worth filling.

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

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

States a specific verb and resource: returns the calling OAuth client's id and granted scopes. It is clearly distinguishable from every admin_* sibling, which are diagnostics about findings, conversions, telemetry, or errors rather than caller identity.

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

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

Gives concrete usage context: 'Use to verify that admin auth is wired correctly end-to-end.' No competing alternative is named and no exclusion is stated, but for a zero-parameter identity diagnostic there is little ambiguity to resolve.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavior beyond that: fuzzy trigram fallback semantics and the matchType signal, the miss path returning suggestions plus a hint, the source-file duality of type=object vs type=door, and the concise-vs-detailed metadata shape. Some of the returned-field listing overlaps the existing output schema, which keeps this 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-loaded with the purpose, then the exclusion list, then constraints, then worked examples — each block earns its place and the examples disambiguate fuzzy vs substring hits. It is long and a few clauses (the return-field inventory) restate schema/output-schema content, so not a 5.

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

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

For a 6-param, zero-required, read-only lookup with an output schema and full annotation coverage, the description supplies everything needed to choose the tool, pick the right argument mode, and interpret a miss or a fuzzy hit. Nothing material 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 baseline is 3, and the description adds meaning beyond it: the exactly-one-of constraint across name/hash/search, how type narrows multi-type hits, and the non-obvious note that type reflects the SOURCE FILE (one model appearing as both object and door). It does not re-specify the fuzzy threshold or decimal-hash rejection, which the schema already documents.

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 (resolve RedM/RDR3 game-data assets by name, hash, or partial search) and names the exact set of covered types. It explicitly distinguishes itself from lookup_native, discovery_lookup, location_lookup, and semantic_search, so an agent can route 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 'NOT for' block enumerates alternatives with the discriminating signal (64-bit native hashes vs 32-bit asset hashes, places, behavior queries) and names the correct sibling for each. It also states the mutual-exclusion rule ('pass exactly ONE of name/hash/search') and when to narrow with type.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description still adds value beyond that by disclosing the return shape ({path, title, chunks}[]) and by stating the negative behavior (not a content search), though it says nothing about result size, pagination, or defaults when both optional params are omitted.

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, zero padding: scope first, routing second, return shape last. Each 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, the description compensates by stating the return structure, and it fully covers routing relative to siblings. It stops short of explaining the effect of omitting both optional parameters (potentially an unbounded enumeration) and any result limits, which are the remaining unknowns for a 2-param discovery 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 description coverage is 0%, so the description carries the burden, and it only references 'category/namespace' as a phrase without explaining what a namespace means, how it relates to category, whether it is a prefix filter, or what happens when both are omitted. The enum values live in the schema, so this is the minimum viable level for a low-coverage 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 ('Enumerate RedM/RDR3 doc paths in a category/namespace') and immediately sharpens the scope by saying it is not a content search. The agent can distinguish it from get_document, grep_docs, and semantic_search 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 an explicit use case ('discover what exists before calling get_document or a targeted grep_docs') plus explicit exclusions, naming the correct sibling for each alternative lookup type (semantic_search for behavior/concept, grep_docs for tokens). This is textbook when/when-not/alternative routing.

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

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

Annotations already declare readOnly/destructive/openWorld, lowering the bar, but the description adds genuine behavioral context: returns complete records with source commit and line ranges, pagination via nextOffset, fetching records with get_document, and the responseFormat:'concise' collapse behavior. It stops short of noting result-size limits or rate behavior, so a 4 rather than 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?

The description is dense and fairly long, but it is front-loaded with the covered kinds and most sentences carry distinct routing or semantic payload. The kind enumeration is repetitive with the schema enum, which slightly dilutes efficiency.

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 10 parameters, 16 kind values, nested objects, and an output schema, the description covers the ambiguous dimensions an agent needs: what kinds exist, which parameter shapes apply per kind, alternatives, pagination, and response shaping. Nothing critical 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?

With 50% schema coverage, the description compensates well: name is exact, parent is an exact dictionary/model/group, search is keywords or a partial identifier, hash accepts 32-bit hex/decimal, and near finds IMAPs within a 3D radius. responseFormat is also explained beyond the schema. namespace and the limit/offset details are only lightly covered, keeping this from a 5.

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

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

States a specific verb and resource ('Look up complete structured RedM records') and then enumerates the covered kinds (animation, audio, imap, clothing, propset, control, bone, etc.). It clearly disambiguates itself from the sibling tools asset_lookup, lookup_native, semantic_search, and grep_docs, so an agent can route correctly without opening the schemas.

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

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

Explicitly names the alternatives and the condition that selects each: 'For model assets use asset_lookup, callable natives use lookup_native, behaviors use semantic_search, and every raw reference or unsupported format uses grep_docs.' It also gives concrete call examples and special-case rules (entity_extension uses model as name, bone uses model as parent).

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), yet the description adds substantial behavioral context: missing documents return available headings and recovery hints, deep sections include the parent's introduction, pages over ~18k tokens are always trimmed, and omitted sections are surfaced with heading plus read_lines range. This is well beyond what the annotations provide.

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?

Purpose and the routing rule are front-loaded in the first two sentences, and no sentence is pure filler. It is dense with many distinct clauses, which costs some readability, but nearly every clause carries actionable routing or behavioral 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, so the description carries the return-value burden, and it does: structured discovery records include metadata and commit/line references, long pages are trimmed with omitted sections listed, and missing documents yield headings plus recovery hints. 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 description coverage is 100%, so the schema already documents path, query, heading and maxTokens in detail; the description largely reinforces these. It adds minor interplay context (query ranking with a default ~6000 budget when maxTokens is unset) but no significant meaning the schema lacks, so the baseline 3 is correct.

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

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

States a specific verb+resource ('Fetch a RedM/RDR3 document or a complete discovery:<id> record') and immediately anchors it to paths returned by browse, semantic_search, discovery_lookup and grep_docs. An agent can distinguish this retrieval tool from grep_docs, lookup_native and read_lines 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?

Explicitly routes the agent: 'for animation/audio/IMAP/... start with discovery_lookup; for individual natives use lookup_native', and 'arbitrary source line ranges require read_lines with the raw sourcePath'. It names the alternatives and the conditions that select them, including when NOT to use this tool.

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

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

Annotations already establish the safe read-only, non-open-world profile, so the bar is lower. The description still adds real behavioral context: a one-call-per-session contract and a cost signal ('Cheap, no embedding'), which annotations cannot convey.

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

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

Front-loaded with purpose, then usage, then contents, then cost — a sensible information hierarchy. Each clause carries information, though the middle enumeration of covered topics is dense and slightly 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?

No output schema exists, so the description must describe what the guide returns, and it does: result modifiers, invokeNative vs invokeNativeByHash, type mapping, pointer gotchas, and worked examples. For a static reference-loading tool this covers everything an agent needs.

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

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

Only one parameter, and schema coverage is 100% with an enum that fully documents 'js'/'lua'. The description merely restates the two allowed values, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Load') and resource ('calling-convention reference for RedM/RDR3 natives') with the two target languages named. It implicitly differentiates from the native-doc siblings by explaining that this guide exists because 'every native doc page only shows Lua examples,' though it never names a sibling tool 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?

Clear when-to-use directive: 'Call ONCE per session before writing native-calling code,' which also encodes an exclusion (do not call it repeatedly). It identifies the audience (JS/TS authors needing translation) but does not name the sibling (lookup_native) as a companion or 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?

Annotations already declare readOnlyHint/destructiveHint=false, so safety is covered. The description adds return behavior (path + 1-based line numbers, long lines windowed), multiline semantics, and retry guidance via prior_attempt, which is real behavioral value beyond the annotations.

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

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

Front-loaded with purpose, then alternatives, then parameter notes, then retry guidance. It is dense and long for a description, but nearly every clause carries actionable information, so waste is minimal.

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

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

No output schema exists, but the description compensates by describing the return shape (paths and 1-based line numbers) and windowing. It also points to read_lines for surrounding content, covering the follow-up gap for a 10-parameter 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 90%, so the baseline is 3, and the description still adds meaning: Rust regex syntax, case-insensitive-by-default, filesOnly returning only paths, and contextBefore/contextAfter including surrounding lines. It also advises preferring targeted patterns over large alternations.

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: finding exact tokens/patterns in raw RedM/RDR3 docs including Lua tables and native notes. It names concrete use targets (walkstyle names like MP_Style_Casual, scenario keys, framework symbols) that pin down the resource precisely.

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 routes the agent: prefer discovery_lookup for structured catalogs, asset_lookup for model assets, lookup_native for callable natives, semantic_search for behaviors, and reserves grep_docs as the fallback for unsupported formats or catalog misses. Both when-to-use and when-not-to-use are stated.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real context beyond that: it enumerates what each category contains and what the categories are used for, letting an agent predict the effect of subsequent filter usage. It doesn't discuss result size or output shape, but an output schema exists to carry that.

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

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

Purpose and the routing rule are front-loaded in the first two sentences; the category enumeration follows and is dense but earns its place because it is effectively the tool's contract. The trailing category list is long for a description, though each item adds disambiguation value.

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

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

For a zero-required-parameter orientation tool with an output schema, the description supplies everything needed: when to call it, what it is not, what the filters mean, and how its output should be used downstream. Return-value details are correctly left to the output schema.

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

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

Schema description coverage is 0%, so the description must carry the meaning of the single `category` enum. It does: every enum value (natives, vorp, rsgcore, oxmysql, discoveries, jo_libs, cfx, guides, learnings) is listed and several are annotated with their sub-namespaces. It stops short of stating explicitly that the parameter filters the returned list, which keeps it from a 5.

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

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

The description states a specific verb and resource ('list available doc categories and their namespaces') and frames it as an orientation step. It explicitly contrasts itself with content search and names the sibling tools whose filters it feeds ('browse' / 'semantic_search'), so an agent can distinguish it from grep_docs, browse, and semantic_search immediately.

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

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

It gives explicit timing ('use once at session start, or when unsure') and the downstream condition ('before applying a category= / namespace= filter'). The negative case is stated outright ('NOT a content search'), removing the main ambiguity an agent would have.

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

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

Annotations already cover the safety profile (readOnly=true, destructive=false, openWorld=false), and the description adds rich behavioral detail beyond them: result shape (world coords [x,y,z] with z null for 2D sources), town/district/state tagging, link semantics (interior → members, shop/door → site), the door-visibility rule ('Doors only appear for type=door or door/gate/cell words'), and search fallback behavior when a town filter 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?

Front-loaded with purpose and usage before diving into modes and results; every sentence carries information. It is dense and parenthetical-heavy, which slightly hurts scannability, 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 9-parameter tool with no output schema, the description fully documents the return format (coords, town/district/state, relation links) and query modes. An agent has everything needed to call it correctly without opening the schema.

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

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

Schema coverage is 67%, and the description meaningfully compensates by explaining how parameters interact: 'search' filters to a named town with nearest-match fallback, 'near'/nearPlace drive proximity queries, 'radius' defaults to 250m, and nearPlace is resolved like search. Only limit/offset go unexplained, but those are standard pagination.

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

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

States a specific verb+resource (find places on the RedM/RDR3 map and how they relate) and goes further by enumerating covered entity types (states, districts, towns, shops, interiors, landmarks, graves, doors). It explicitly distinguishes itself from siblings: 'Models/props use asset_lookup; IMAP chunks discovery_lookup.'

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 concrete trigger phrases ('where is X', 'coordinates of …', 'what is near …'), names the alternative tools for adjacent domains, and documents each mode (search, name, type, near, nearPlace) with the condition that selects it. Nothing about when-to-use is left to inference.

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

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

Annotations already declare readOnly/destructive/openWorld, but the description adds substantial behavior beyond them: exact-first with ILIKE substring fallback, the shape of the response (findings[], refDocs[]), the inline-vs-fetch branching for refDocs, and miss behavior including cross-game and 'in neither database' reporting.

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?

Purpose and trigger conditions are front-loaded, and almost every clause carries actionable information. It is nonetheless a long block of prose that would scan better as short bullets for the findings/refDocs workflow.

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 lookup tool with a rich output schema, the workflow guidance (follow findings[].id via get_document, run refDocs[].fetch when content is null) is exactly the extra context an agent needs to act on results, and the miss semantics prevent dead-end retries.

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

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

Adds meaning beyond the 75%-covered schema: hash accepts 0x-prefixed or bare and is case-insensitive, and name resolves exact first then falls back to ILIKE substring. It does not address the limit parameter or reiterate namespace scoping beyond the schema's own text.

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

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

States a specific verb+resource (resolve a RedM/RDR3 SCRIPT native by hash or name) and immediately characterizes it as O(1), exact. It also distinguishes its domain from siblings by explicitly ruling out game-data hashes and routing those to grep_docs.

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

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

Gives concrete trigger patterns (Citizen.InvokeNative(0x...), GetHashKey('NAME'), SCREAMING_SNAKE_CASE names in Lua/JS/TS) and a clear when-not with an alternative ('NOT for game-data hashes … use grep_docs'). It also warns not to call GTA5/FiveM-only hits from RedM.

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

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

Annotations already declare read-only and non-destructive safety. The description adds critical behavioral context beyond that: full bodies of the largest rdr3_discoveries tables are not in the vector/heading index (only an ~80-line preview), get_document cannot resolve synthetic 'lines N-M' offsets, and calls are capped at 400 lines. This is exactly the kind of non-obvious behavior 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?

The description is long but front-loads the core action and workflow, then moves to alternatives and constraints. Most sentences earn their place by preventing specific failure modes, though the density could be trimmed slightly without losing essential guidance.

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

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

For a complex retrieval tool with no output schema, the description is complete: it explains what the tool returns, how to select ranges, hard limits, why competing tools fail for this use case, and exactly when to use it relative to a large sibling set.

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

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

Schema description coverage is 100%, so the schema already documents 1-based inclusive start/end, the 50-line default window, and the 400-line cap. The description largely restates these semantics and does not add new parameter syntax or format details beyond tying start to a grep_docs hit line number. Baseline 3 is appropriate.

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

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

States a specific verb and resource with scope ('Read an exact line range from a raw RedM/RDR3 doc file by absolute line number') and explicitly names it as the windowed-read companion to grep_docs. It is easily distinguishable from all 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?

Provides explicit when-to-use guidance tied to a concrete workflow ('When grep_docs returns a hit at path:line... call read_lines') and names alternatives with conditions: get_document for prose .md headings, grep_docs for searching values, lookup_native for script natives. Also explains why semantic_search and get_document cannot substitute here.

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

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

Annotations already declare a safe read-only, non-destructive, non-open-world profile, and the description adds substantial behavior beyond them: hybrid mode fuses vectors, full-text and structured discoveries then reranks; results are ranked snippets; get_document opens returned paths including discovery:<id>. It also discloses what each mode retrieves and that community findings are merged by default.

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?

Purpose and sibling routing are front-loaded, and nearly every sentence carries operational value. It is on the dense/long side with several chained clauses, but the density is justified by the tool's complexity (7 params, three modes, many categories) rather than padding.

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

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

For a complex hybrid-search tool with 7 parameters, a nested prior_attempt object, and no output schema, the description is thorough: it explains retrieval behavior, the return shape (path, breadcrumb, heading, snippet, score), how to follow up, and the retry protocol. Nothing an agent needs to call or interpret 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 schema already documents all seven parameters (baseline 3). The description still adds real meaning: it defines what mode=semantic vs mode=lexical actually retrieve, expands category=cfx's scope and notes category=learnings returns only findings, and gives the precise trigger for prior_attempt. These additions go beyond the enum labels but stop short of covering every parameter nuance.

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 RedM/RDR3 docs by behavior, concept, or token') with concrete query examples ('teleport player', 'spawn vehicle'). It explicitly names the sibling tools it is not (lookup_native, asset_lookup, discovery_lookup, grep_docs) and the conditions that route to each, so an agent can distinguish it 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 routing rules: specific native -> lookup_native, models -> asset_lookup, animation/audio/IMAP/etc records -> discovery_lookup, raw refs -> grep_docs. It also explains mode selection, category filtering, and the retry protocol via prior_attempt, plus how to open results with get_document. This is a complete when-to-use/when-not map.

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

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

Goes well beyond the annotations: findings are merged into default semantic_search results, category 'learnings' filters to findings only, credentials cause rejection, new contributors' submissions are held for admin review, and submissions are rate-limited per user. These are non-obvious behavioral traits the annotations (readOnlyHint=false, idempotentHint=false, etc.) cannot convey.

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

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

Leads with the one-line purpose, then uses clearly labeled WHEN / WHEN NOT blocks and a closing operational note. Despite its length, every sentence carries actionable content and the critical routing info is front-loaded.

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

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

For a write tool with no output schema, the description covers the full lifecycle an agent needs: what to submit, what to exclude, moderation delay, rate limiting, and how the data resurfaces via search. Nothing material 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 adds genuine guidance beyond the schema: title should be short and searchable and body should explain WHY not just WHAT. It doesn't detail the tags/category/source fields beyond the schema, keeping it at 4 rather than 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 (share/write) and resource (a verified RedM/RDR3 finding) plus the goal (so the next agent can find it). It clearly distinguishes itself from read-side siblings like semantic_search and grep_docs by being the contribution path into the corpus.

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

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

Explicit WHEN and WHEN NOT lists with concrete triggers ('burned multiple iterations', 'undocumented quirk') and named prerequisites/alternatives ('verify with semantic_search/grep_docs first'). It even excludes project-specific content, leaving nothing to inference.

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