redm-mcp

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

Beyond the readOnlyHint annotation, the description discloses critical behavior: refreshed upload links before conversion, 24-hour expiry, 15-minute ZIP validity, untrusted file/clip names, and prohibitions on publishing transfer URLs or claiming automatic installation. This gives the agent strong operational and security guardrails.

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 but every sentence adds value: access requirements, operation semantics, result contents, expiry, and safety constraints. The most important guidance is front-loaded, and the security warnings are concise rather than rambling.

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

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

The description covers the result format, expiration, access requirements, and safety constraints. An output schema exists to define the exact response shape, so the description does not need to enumerate return fields, and nothing necessary 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 schema only defines jobId with a UUID format and no description, so the description must add semantic meaning. It does so by explaining the job is the agent's own conversion job and that jobs expire after 24 hours, though it stops short of explicitly stating that jobId comes from the conversion-starting tool.

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

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

The description clearly states the tool reads a conversion job and, when succeeded/partial, returns download artifacts and integration steps. The title reinforces this as a status/download operation, distinguishing it from sibling tools like admin_start_animation_conversion and admin_create_animation_conversion.

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 access requirement, that the agent should read its own job, and that jobs expire after 24 hours. It does not explicitly name the sibling tool used to start a conversion, but the context strongly implies this tool is for checking and retrieving results of an existing conversion.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses access requirements, storage retention, no automatic installation, raw 512 KiB chunk semantics, idempotent retry via requestId reuse, and constraints like target mp_male and readable RSC7 v46 YCD. This is meaningful operational context that the annotations alone do not convey.

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

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

The description is dense but every clause carries necessary information: prerequisites, destination decision, targetResource conditional, upload mechanics, limits, formats, and follow-up step. It front-loads the key constraints before diving into procedural details.

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

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

For a multi-step upload-and-create flow with 5 parameters and an output schema, the description is complete: it specifies how to prepare inputs, what to send, what to expect (returned PUT URLs/headers), and the next tool to call. The presence of an output schema means return-value details do not need to be repeated.

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 free text adds meaning that the schema leaves implicit: requestId is a reusable retry key, files need precomputed size/SHA-256 and size limits, targetResource controls asset-only vs preview bundles, and resourceName labels the output package. Since schema coverage is 60%, the description compensates fully, and rootMotion is already well documented in the schema.

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

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

The description names the concrete action (upload raw chunks to create an animation conversion), scopes it to RedM, and lists accepted input formats (FiveM YCD / Mixamo FBX). It also positions the tool relative to admin_start_animation_conversion by explicitly saying to call that sibling after uploads, so an agent can decide which tool to invoke.

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 conditions: animation conversion access is required, destination must be established first, targetResource should be set to an existing script/dev resource or omitted for standalone preview, and upload must be followed by admin_start_animation_conversion. It also lists exclusions (no base64, local paths, source URLs, input ZIPs/scripts), which removes ambiguity about what this endpoint accepts.

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 destructiveHint annotation by disclosing cascading deletion of native links, rewriting finding_context, immediate surfacing effects, and a semantic_search cache lag of up to 10 minutes. It also clearly states irreversibility and the safety precondition.

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 information-dense but each sentence earns its place: scope, cascade behavior, cache lag, irreversibility, preflight inspection, and alternatives. It is front-loaded with the primary purpose and keeps closely related guidance together.

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 admin operation with no output schema and a single parameter, the description covers the action, side effects, eventual consistency, reversibility, prerequisites, and alternatives. Nothing an agent needs to safely select and invoke the tool is missing.

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

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

Schema coverage is 0%, but the description compensates by contextualizing the single parameter: it identifies the finding as a community finding, restricts to the current deployment, and implies the id can be obtained via admin_get_finding. It does not explicitly label the `id` field, but with one obvious integer parameter this is sufficient.

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 ('permanently delete'), a specific resource ('community finding'), and adds scope constraints ('Admin-only', 'THIS deployment's game'). It clearly distinguishes the tool from sibling tools like admin_get_finding and admin_update_finding.

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 guidance on when to use the tool: only for junk findings, and only after inspecting with admin_get_finding. It also names the preferred alternative, admin_update_finding, for non-junk corrections, making selection unambiguous.

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 provide readOnlyHint=true, so the read-only nature is already known. The description adds important behavior beyond annotations: findings before IP capture show as authorIp:null, and the tool spans both games with each row indicating its game. These are non-obvious details that help the agent interpret results correctly.

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 front-loaded: purpose first, then use cases, then parameter behavior, then edge cases. Every sentence adds value, and there is no filler. The structure helps an agent quickly grasp the tool's purpose and usage.

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

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

Given the tool's complexity (grouping, output fields, edge cases, cross-game scope) and the absence of an output schema, the description provides sufficient detail: it enumerates the output fields, mentions ordering, and covers the null IP and cross-game quirks. It also references sibling tools for follow-up, making the context complete for an agent 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 description coverage is 0%, so the description carries the burden. It explains sinceDays ('counts only recent submissions') and authorIp ('returns that one author'), but does not explicitly describe the limit parameter. However, limit is a common, self-explanatory parameter (max 200), so the description compensates adequately for two of three parameters.

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

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

The description clearly states the tool groups findings per author IP with a specific list of output fields (count, first/last submission, games, categories, tags, latest title) and order (by volume). It also distinguishes itself from siblings admin_list_findings and admin_search_findings by explicitly naming them as alternatives for pulling individual rows.

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

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

The description gives explicit use cases (spot flooding contributor, find IP behind bad findings) and directs the agent to the correct follow-up tools (admin_list_findings/admin_search_findings with authorIp). It also explains the meaning of sinceDays and authorIp parameters, leaving no ambiguity about when 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 declare readOnlyHint=true and openWorldHint=false, so the read-only safety profile is covered. The description adds useful behavioral context beyond annotations: it is admin-only, returns author IP, exposes auto-linked natives, and includes view/surface counts. No contradiction with annotations exists.

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 two tightly packed sentences: the first front-loads purpose and returned fields, the second gives the surrounding workflow. There is no wordiness, filler, or repetition of schema details.

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

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

For a single-parameter read-only get tool with no output schema, the description covers the key return fields and the calling workflow. It could go slightly further by clarifying the exact shape of linked natives or telemetry counts, but the provided information is sufficient for correct invocation in most cases.

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%, but the description compensates by clarifying that the single 'id' parameter is a finding id and by telling the agent where the id comes from (admin_list_findings/admin_search_findings). This adds semantic meaning the bare integer schema does not provide.

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

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

The description clearly states the operation: admin-only retrieval of full finding details by id, and enumerates the returned content (title, body, tags, author IP, game, linked natives, view + surface counts). This distinguishes it from the sibling list/search tools, which are summaries or filters, and from update/delete tools.

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

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

The description explicitly places the tool in a workflow: use it after admin_list_findings/admin_search_findings to inspect a single finding, and before admin_update_finding/admin_delete_finding. However, it does not explicitly differentiate from the admin_telemetry sibling despite the title mentioning telemetry, so the guidance is strong but not fully complete.

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

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

Beyond the readOnlyHint annotation, the description discloses admin-only access, newest-first ordering, cross-game behavior, exact returned fields, and limit defaults/maximums. This is substantial behavioral context that the annotation alone does 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?

The description is dense but well-organized: purpose and output fields first, then filter behavior, then sibling alternatives. Every clause adds useful guidance without 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 tool with no output schema and six parameters, the description covers return fields, ordering, filter semantics, defaults, and sibling alternatives. The only minor gap is category matching behavior, but the overall definition is complete enough 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?

With 0% schema description coverage, the description compensates well by explaining search semantics, tag matching, authorIp exact matching and its source, sinceHours narrowing, and limit behavior. However, the category parameter is only named without clarifying whether it is an exact match or how values are constrained.

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

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

The description opens with a specific verb and resource: 'Admin-only: list community findings (learnings), newest first.' It names exact returned fields and clearly distinguishes itself from sibling tools like admin_search_findings and admin_get_finding.

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 explicitly explains when to use each filter (search, tag, category, authorIp, sinceHours) and points to admin_search_findings for relevance-ranked search and admin_get_finding/admin_update_finding/admin_delete_finding for follow-up actions. This gives an agent concrete routing guidance with no ambiguity.

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=trueestr, but the description adds substantial non-obvious behavior: metrics are scoped to the `redm` game, pre-cutover rows with `game IS NULL` are excluded, cross-game metrics read the same on both endpoints, and defaults are specified (168h / 14d). It also discloses per-metric data nuances like 'usage counters are global, not per game.' No contradiction with annotations.

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

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

The description is long due to the 50-metric enumeration, but each metric line is concise and informative, earning its place. It is front-loaded with the core purpose and parameter rules before the metric list. The sheer volume is a minor readability cost, but the structure is logical and without fluff.

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, the description provides rich detail about each metric's contenthare (e.g., calls, latency, error rates, fallback effectiveness). However, it never states the exact response format or what happens on invalid combinations (e.g., `sinceHours` on a days-bound metric), leaving some operational ambiguity for an agent.

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 full responsibility. It explains `metric` with a complete list of valid values and what each returns, describes the temporal semantics of `sinceHours` and `days` including defaults and which metrics they apply to, and warns about cross-game behavior. This compensates fully for the absent schema descriptions.

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

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

The description clearly states 'Admin-only: read one named metric backed by a postgres view or core query,' giving a specific verb ('read'), resource (named metric), and context (admin-only). It enumerates every available metric with a one-line behavior summary, making it easy to distinguish this from sibling admin tools like admin_telemetry or admin_tool_errors.

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 when to use `sinceHours` vs `days`, notes which metric groups accept each window, and states that metrics are scoped to the `redm` endpoint except cross-game variants. It does not explicitly contrast against sibling admin tools or state what happens when both `sinceHours` and `days` are passed, but the context for invocation is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only safety profile is covered. The description adds valuable behavioral context: args are redacted, data includes IP and OAuth client ID, and it is restricted to the redm game. This goes beyond the annotations by specifying what data is available and the redaction behavior, without contradicting the readOnly hint.

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

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

The description is a single paragraph but each sentence adds value: purpose, data fields, filters, limit, game scope, and use case. It is front-loaded with the admin-only read context and does not waste words, though it could be slightly more compact by merging some clauses.

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

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

The description covers the key fields returned, filter options, limit behavior, and the redm game restriction, which is sufficient for an agent to understand the tool's scope. It lacks explicit mention of pagination beyond the limit, but for a read-only admin tool with no output schema, this is minor. The use case guidance and parameter semantics make it complete enough 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 coverage is 0%, so the description carries full responsibility for parameter meaning. It explicitly explains all four parameters: discordId and tool as filters, ok=false to see only failures, and limit with default 30 and max 200. This fully compensates for the empty schema descriptions and gives the agent everything needed to construct a valid 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 admin-only read operation with a clear resource (recent tool calls) and lists the exact data fields returned (redacted args, duration, IP, verified Discord ID/username, OAuth client ID, outcome). The description distinguishes this from sibling admin_tool_errors by focusing on all calls, not just failures, and from admin_telemetry by scoping to per-tool/per-user debugging.

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 says 'Use to debug a specific tool or inspect one Discord user's calls' and describes optional filters for discordId and tool, plus ok=false for failures. It does not explicitly name alternatives, but the use case is clear and the sibling list includes admin_tool_errors for error-only queries, which is implied rather than stated.

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

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

Annotations already mark the tool as read-only, and the description adds substantial behavioral context: it is admin-only, scoped to this deployment, uses vector + PostgreSQL full-text search fused via RRF and reranked, attaches admin-only fields, supports exact post-filters, and has a default limit of 10 with max 25. This goes well beyond what the annotations alone convey.

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

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

The description is dense but every clause earns its place: permission scope, search behavior, result fields, use cases, sibling differentiation, filters, limit, and deployment scoping are all packed in without filler. The most important information is front-loaded, starting with 'Admin-only' and the core action.

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

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

For a 5-parameter search tool with no output schema, the description is largely complete: it explains the query, filters, limit, retrieval method, and returned admin fields. The main missing piece is the meaning of `mode`, and the return shape is only implied through the listed admin fields. Still, an agent has enough to invoke the tool effectively with the default/most common settings.

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 of explaining parameters. It does well for `query` (natural-language or token), `authorIp` and `tag` (exact post-filters), and `limit` (default 10, max 25). However, it never explains the `mode` parameter, which has enum values `hybrid`, `semantic`, and `lexical`; an agent may not understand when or why to set it. This is a notable gap but most parameters are well 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?

The description opens with a specific verb and resource: 'rank community findings' via hybrid retrieval, and clearly identifies admin-only behavior. It distinguishes itself from `semantic_search` by the admin fields attached and from `admin_list_findings` by relevance ranking vs plain ILIKE filtering. An agent can tell exactly what this tool does and how it differs from its 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 explicitly names concrete use cases: finding a complained-about finding, spotting near-duplicates before editing/merging, and auditing query results. It also contrasts this tool with `admin_list_findings`, saying that one is a plain ILIKE filter while this one is relevance-ranked. This gives clear guidance on when to choose it over an 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 mark idempotentHint true, but the description adds significant detail: the access requirement, the return-immediately behavior, the polling cadence, the packaging of YCDs with preview scripts, and the crucial caveat that success means offline validation only. None of this contradicts the annotations, and it substantially enriches the agent's understanding of side effects and 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?

Every sentence earns its place: requirement, precondition, idempotency, return behavior, polling guidance, packaging detail, and success meaning. It is front-loaded with the most critical constraint ('Requires animation conversion access') and wastes no 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 single-parameter tool with an output schema, the description covers prerequisites, invocation timing, idempotency, return behavior, polling strategy, content packaged, and success criteria. Nothing an agent needs to call it correctly is missing; the output schema covers return values.

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 0% schema description coverage, the description must compensate. It implies that the single required jobId corresponds to an upload ('Start after every upload succeeded'), but it never explicitly states 'jobId is the ID of the upload to convert.' The implicit meaning is strong given the tool name, but not fully explicit; this is a minor gap, so a 4 is warranted.

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 clear verb and resource ('Start RedM animation conversion') and immediately distinguishes it from siblings by saying 'Start after every upload succeeded' and by naming the status tool for polling. It also clarifies the packaging of RedM YCDs, making its purpose unambiguous and distinct from admin_create_animation_conversion.

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

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

It provides explicit when-to-use guidance ('Start after every upload succeeded') and points to the alternative for monitoring ('poll admin_animation_conversion_status no more often than every 5 seconds'). It also states a prerequisite ('Requires animation conversion access') and warns about idempotency, giving the agent clear routing and call-pattern instructions.

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

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

Beyond the readOnlyHint annotation, the description discloses the default time window (168 hours), scoping to the redm game, and the exclusion of pre-cutover entries where game IS NULL. It also maps out the filter behavior for tool and sinceHours. This is substantial behavioral detail that gives the agent a faithful model of what data the snapshot includes, with no contradiction to annotations.

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

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

Three sentences with no redundancy: the first front-loads the core metric list, the second covers parameters and scoping, and the third routes to siblings. Every clause adds value, and there is no repetition of schema or annotation 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?

Even without an output schema, the description enumerates exactly what an agent will receive (calls, errors, percentiles, unique counts), explains the default window and filters, and provides the follow-up workflow. Nothing needed to decide whether to call the tool or interpret its results 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 0%, so the description carries the full burden of explaining both parameters. It states that sinceHours defaults to 168 (7d) and that the optional tool filter 'narrows to one,' which fully disambiguates the two properties. The numeric min/max is already in the schema, so no additional range explanation is necessary.

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 'Admin-only: per-tool health snapshot' followed by a precise enumeration of metrics (calls, errors, error %, latency percentiles p50/p95/p99, unique IPs/sessions), making the tool's function unmistakable. It explicitly emphasizes 'per-tool' aggregation, which distinguishes it from broader admin tools, and the title further narrows the 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?

Explicitly instructs to 'Use to spot tools that are slow, failing, or unused before drilling in with admin_tool_errors / admin_recent_tool_calls,' naming the exact alternatives and the intended sequencing. It also clarifies admin-only access, the optional tool filter, and game scoping, leaving no ambiguity about when this tool should be selected.

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?

Even though readOnlyHint already marks this as read-only, the description adds valuable behavior: it counts only thrown exceptions, excludes errText results, excludes pre-multi-game rows with game IS NULL, and scopes to the redm game. No contradiction with the annotations.

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

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

The description is dense but not padded: the core result is front-loaded, the exclusion and scope caveats are packed into parentheticals, and the use case is the final sentence. Every clause adds 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?

It covers the query's shape, exclusions, scope, and use case, which is strong for a read-only admin tool. However, since there is no output schema, the return contract is only partially specified and relies on a reference to the v_tool_errors view, and the optional parameters remain undocumented.

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

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

The input schema has 0% description coverage and the description never explains what `tool` or `sinceHours` control. `sinceHours` is inferable from its name, but `tool` remains ambiguous as a filter or grouping input, and there is no guidance on behavior when parameters are omitted.

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 anchors on a specific resource ('tool failures') and a clear grouping key ('errorName'), and names the selected fields ('latest_message and last_seen'). This is enough to separate it from siblings like admin_recent_tool_calls even though no sibling is explicitly named.

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 final sentence gives an explicit use case: triage what's actually breaking before grepping container logs. It also states when the tool is not applicable by noting logical errText results are excluded because they have no errorName, and clarifies the game 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?

Beyond annotations, the description discloses substantial side effects: title/body changes re-embed the finding, body changes re-derive auto-linked natives while keeping explicit links, finding_context blurbs refresh, and semantic_search results may lag up to 10 minutes. The ownership refusal is also called out. No contradiction with annotations exists.

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 but every sentence earns its place: scoping, parameter semantics, side effects, prerequisites, and cache lag are all packed without filler. The key usage constraint is front-loaded before the behavioral details.

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

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

For a mutation tool with six parameters and no output schema, the description covers what changes, how changes propagate, what is cleared by null, what is preserved, prerequisites, ownership limits, and cache lag. An agent has enough context to decide whether and how to invoke the tool correctly.

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

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

Schema description coverage is only 33%, so the description carries the burden, and it delivers: it explains id plus partial updates, tags replaces the whole list, category and source accept null to clear, and body must be the full corrected markdown. This adds meaning well beyond the raw schema fields.

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

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

The description opens with a specific verb and resource: 'Admin-only: edit an existing community finding in place.' It clearly distinguishes the tool from siblings like admin_delete_finding, admin_get_finding, and share_finding by focusing on in-place edits of an existing finding.

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 when to use the tool (edit an existing finding), gives a prerequisite ('Read the current text with admin_get_finding first'), and warns against common misuse ('send the full corrected body, not a diff'). It also explicitly limits use to findings of the current deployment's game, with the other game's findings refused.

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 set readOnlyHint=true, indicating a read-only operation. The description adds behavioral context beyond annotations: it is admin-only, requires the 'admin' scope, and returns the client id and scopes. This explains the access restriction and intended verification purpose, which annotations do not cover.

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 three sentences, each earning its place: it states what it does, when to use it, and who can access it. It is front-loaded with the core function and contains no fluff 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 simple diagnostic with zero parameters and no output schema, the description fully covers what the tool returns, its intended purpose, and its access restrictions. An agent has everything needed to decide when to call it and what to expect.

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

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

The tool has zero parameters and an empty input schema, so schema coverage is 100%. With no parameters, the description does not need to elaborate on parameter meaning. Baseline for zero-param tools is 4, and the description appropriately omits parameter details.

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

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

The description clearly states the verb 'Returns' and the specific resource: 'the calling OAuth client's id and granted scopes.' It also labels it an 'Admin diagnostic,' distinguishing it from sibling admin_* tools that perform mutations or queries on findings. The purpose is unambiguous.

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

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

The description gives an explicit use case: 'Use to verify that admin auth is wired correctly end-to-end.' It also indicates it is admin-only and visible only to clients with the 'admin' scope, implying it should be used by admin clients. It does not explicitly mention alternatives, but there are no direct sibling tools for this diagnostic, so the guidance is sufficient.

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

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

Beyond the readOnlyHint=true annotation, the description discloses substantial behavioral traits: O(1) lookup against pre-parsed tables, typical latency (p50 ~15ms, p95 ~65ms), exact-match semantics (name/hash return 0 or 1), fuzzy trigram fallback behavior with the exact trigger condition, and the 'type' source-file nuance (same asset can appear under multiple types with different metadata). It even warns about decimal hashes and why fuzzy rarely fires without type narrowing. This is far more than the annotation provides and fully arms the agent.

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 every section earns its place: purpose, return format, performance, not-for alternatives, parameter usage, type nuance, fuzzy behavior, and examples. It is front-loaded with the one-sentence purpose, uses clear section breaks and bullet lists, and avoids fluff. The length is appropriate for a tool with five parameters and nuanced edge cases; it reads as a compact reference rather than padded prose.

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

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

Given the tool's complexity (5 parameters, 5 asset types, fuzzy matching, type source-file ambiguity), the description is remarkably complete. Even with an output schema present, the description explains the non-obvious return fields (matchType, variants, relationship, coords, etc.) and the exact conditions under which different metadata appears. It also covers edge cases like the same asset existing under multiple types and the decimal-hash rejection. There are no obvious gaps that would leave an agent unsure how to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds critical semantics not present in the JSON schema: mutual exclusivity of name/hash/search (the schema does not enforce oneOf), the fact that 'limit' only applies to search, and the exact behavior of the fuzzy fallback (trigram similarity >=0.4, when it fires and when it doesn't). It also provides rich examples for each parameter (e.g., hash 0xBCFD0E7F resolves to a_c_bear_01) and clarifies the exact format expectations. This far exceeds what 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?

The description opens with a clear, specific statement: 'Resolve a RedM game-data asset (ped model, weapon, object, door, vehicle) by exact name, 32-bit hash, or partial-name search.' It explicitly distinguishes itself from sibling tools (lookup_native, grep_docs, semantic_search) in the 'NOT for' section, and even provides the exact output shape (type, name, normalized hash, source file, metadata). This goes well beyond a vague purpose and clearly differentiates from alternatives.

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

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

The 'NOT for' section lists three specific alternative tools with exact use cases (natives -> lookup_native, tokens -> grep_docs, behavior queries -> semantic_search). It also gives clear parameter usage rules ('Pass exactly ONE of name/hash/search'), explains when to use the optional 'type' filter, and includes concrete examples for each parameter mode. This is explicit, actionable guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing the return shape ({path, title, chunks}[]) and by stating this is not a content search, though it says nothing about result volume or pagination for large namespaces.

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

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

Three sentences, each load-bearing: purpose, routing constraints, and return contract. The core action is front-loaded and there is 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?

With no output schema, the description usefully supplies the return shape and the routing context, and read-only annotations cover the safety side. The only meaningful omission is namespace semantics, which matters for a discovery tool that will likely be called with namespace values the agent must infer.

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

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

Schema description coverage is 0% for both parameters. The description only echoes the parameter names ('category/namespace') and adds no meaning—it never explains what a namespace is, how it relates to category, or whether omitting both lists everything. The category enum self-documents in the schema, so the undocumented free-text namespace is the real gap the description fails to close.

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 (enumerate) and resource (doc paths) scoped to a category/namespace, and explicitly positions itself against get_document, grep_docs, and semantic_search so an agent can differentiate 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 when-to-use (discover what exists before fetching) and two explicit when-not-to-use routes with named alternatives: semantic_search for concept lookups and grep_docs for token lookups. This is close to ideal 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?

Read-only behavior is already covered by annotations, and the description adds useful details: complete records with source commit and line range, pagination via nextOffset, near searches restricted to IMAPs, and the discovery:<id> path for get_document. This goes meaningfully beyond the structured fields.

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

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

The description is long but dense and well ordered: purpose first, then parameter semantics, return behavior, pagination, sibling routing, and examples. Every sentence contributes operational value, 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?

Given 9 optional parameters, an output schema, and readOnly annotations, the description covers input modes, result contents, pagination, related-tool routing, and the RedM-only scope. Nothing an agent needs to invoke or disambiguate this tool is missing.

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

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

Schema description coverage is low at 44%, but the description compensates well by explaining name as exact member lookup, parent as exact dictionary/bank/group, search as partial/keyword, hash as 32-bit hex/decimal, kind as domain restriction, and near as a 3D IMAP radius. Only namespace and basic pagination parameters 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 opens with a specific lookup verb and enumerates the exact record families it handles: animations, audio, IMAPs, clothing, wearables, particles, flags, and textures. It also distinguishes itself from asset_lookup, lookup_native, and semantic_search, so an agent can identify this tool 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 explicitly says to use this for literal identifiers even inside large Lua tables and names sibling alternatives for model lookups, 64-bit natives, and behavior explanations. The per-parameter usage rules and concrete examples give clear triggering conditions.

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

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

The annotation readOnlyHint=true already covers the read-only nature, so the description doesn't need to restate it. It adds valuable behavioral context: heading matching is case-insensitive and fuzzy, deep sections include parent introductions, missing documents return available headings and recovery hints. This goes beyond annotations without contradicting them.

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

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

The description is a single dense paragraph but each sentence earns its place. The core purpose is front-loaded, followed by usage guidance and edge cases. It's slightly long but not padded; the structure flows logically from purpose to alternatives to specifics.

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 moderate complexity, the description is complete. It covers path sources, heading behavior, special cases (discovery, Lua keys, source lines), and error handling (recovery hints). An agent has everything needed to call it correctly without external documentation.

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?

Although schema description coverage is 100% (both path and heading are described in the schema), the description adds meaning beyond the schema: it explains that heading is fuzzy and case-insensitive, warns against code symbols, and clarifies that structured records need no heading. This enriches the schema's bare field definitions.

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

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

The description opens with a specific verb and resource: 'Fetch a document or a complete discovery:<id> record', and explicitly names the tools that return the paths to use (browse, semantic_search, discovery_lookup, grep_docs). This clearly distinguishes it from siblings and leaves 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 description provides explicit when-to-use guidance and names alternatives: for animation/audio/IMAP/clothing/etc. use discovery_lookup, for individual natives use lookup_native, for raw source lines use read_lines. It also explains that community findings use learning:N paths and that heading selection differs for structured records. This is exemplary 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 annotations declaring readOnlyHint=true, the description adds significant context beyond that: it discloses the tool is cheap and has no embedding, mentions the specific content covered (result modifiers, invokeNative vs invokeNativeByHash, type mapping, pointer-arg gotchas), and tells the user to call it only once per session. This goes well beyond the structured annotations.

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

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

The description is four sentences, each with a distinct purpose: purpose, usage timing, content scope, and cost/behavior. It is front-loaded with the core action and contains no redundant phrases or 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?

Given the tool has only one parameter and no output schema, the description provides comprehensive context: what it does, when to use it, why it's needed, what it covers, and its low cost. It fully prepares an agent to select and invoke the tool correctly.

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

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

The schema covers the only parameter (language) with a clear enum and description, so the baseline is 3. The description mentions 'in `js` or `lua`' which mirrors the enum but doesn't add new semantic details beyond what the schema already provides.

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

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

The description clearly states the tool loads a 'calling-convention reference for RedM/RDR3 natives' in a specific language, which is a specific verb+resource. It distinguishes itself from sibling tools like lookup_native or get_document by emphasizing that it is the translation guide for JS/Lua authors, addressing a unique gap in the documentation.

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 explicitly says 'Call ONCE per session before writing native-calling code', providing clear when-to-use guidance. It explains why this tool is needed (every native doc page only shows Lua examples) but does not explicitly name alternatives or say when not to use it, so it doesn't reach 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?

Beyond the readOnlyHint annotation, the description discloses return behavior: 'Returns path and 1-based line numbers; long lines are windowed around the match.' It also explains syntax constraints, case handling, and points to read_lines for raw content access. No contradiction with annotations.

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

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

The description is dense but front-loaded: purpose first, then sibling routing, then parameter/return details. The long example list and fallback explanation all earn their place in guiding search behavior.

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 10 parameters and no output schema, the description covers return format, line numbering, long-line windowing, context options, retry behavior via prior_attempt, and linkage to read_lines. Schema covers the remaining parameter details, so nothing essential is left 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 90%, so the schema already documents almost every parameter. The description mostly repeats parameter behavior (contextBefore/contextAfter, filesOnly, multiline, Rust regex) rather than adding new parameter-specific semantics; therefore it stays at the high-coverage baseline.

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

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

The description opens with a concrete verb and resource ('Find exact tokens or patterns in raw documentation') and gives concrete examples of searchable entities. It also distinguishes itself from sibling tools by naming discovery_lookup, asset_lookup, lookup_native, and semantic_search as alternatives.

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

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

Explicit when-to-use guidance is present: 'Use to find every source reference...' and 'grep_docs remains the fallback for unsupported formats or a catalog miss.' It also tells when to prefer each sibling tool, which is strong 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it is an orientation/listing call, explicitly not a content search, and scoped to a fixed set of doc sources. It does not discuss cost, caching, or output shape, but the output schema covers 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?

Front-loaded with the orientation purpose and the when-to-use rule before the category enumeration, and the 'NOT a content search' exclusion is placed early. The long parenthetical namespace lists are useful but slightly noisy; they could be trimmed without losing function.

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-param, read-only listing tool with an output schema, the description supplies everything needed: purpose, timing, exclusions, and the populated category values. Nothing critical is missing, though noting that the filter is optional would make it fully self-contained.

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 optional `category` param has an enum, so the description must carry the load — and it does, enumerating each category with representative sub-namespaces (PLAYER, ENTITY, VEHICLE for natives; menu, notification, callback for jo_libs). It adds real meaning beyond the bare enum list, though it never states explicitly that omitting `category` returns everything.

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 (list doc categories/namespaces) with an explicit negative scope statement ('NOT a content search') that separates it from the sibling search tools. An agent can tell exactly what this returns without opening the schema or 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 precisely when to call it ('once at session start, or when unsure') and what it enables ('before applying a `category=` / `namespace=` filter to browse / semantic_search'). Explicit alternatives are named, so the routing decision is unambiguous.

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

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

Annotations only carry readOnlyHint/openWorldHint, but the description adds substantial behavior: matching order (exact then ILIKE fallback), the full return field set, the findings[]/refDocs[] secondary structures, the inline-vs-fetch protocol for oversized enum tables, and miss behavior (reports the other game's database or fabrication). This is well beyond what the annotations cover.

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

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

The purpose and usage trigger lead the paragraph, then the return-shape details follow. It is long and dense, and the return-structure sentences could be tightened, but nearly every clause carries actionable routing or fetch 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 lookup tool with a rich output schema, a 4-param surface, and sibling ambiguity, the description covers retrieval, fallback behavior, secondary result structures, and the follow-up call needed for large enum tables. An agent has everything required to invoke it and interpret the response 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 75%, and the description adds matching semantics the schema doesn't: hash is case-insensitive with optional 0x prefix, name is exact-first with ILIKE substring fallback, and namespace is only meaningful with name. It does not explain the `limit` param, but that is a minor gap given the schema's own description.

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 (resolve) and resource (RedM/RDR3 SCRIPT native) with the lookup key modes (hash or name) and performance characteristic (O(1), exact). It explicitly distinguishes itself from siblings grep_docs and get_document, so an agent can route without opening another 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 concrete trigger patterns (`Citizen.InvokeNative(0x...)`, `GetHashKey('NAME')`, SCREAMING_SNAKE_CASE names) and an explicit exclusion: game-data hashes for weapons/peds/animations go to grep_docs instead. When-to-use and when-not-to-use are both 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 indicate readOnlyHint=true, but the description adds valuable behavioral context: 1-based inclusive lines, 50-line default window, 400-line cap, and the indexing limitation that semantic_search/get_document cannot reach full table bodies. This goes beyond what annotations provide and helps the agent predict behavior.

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

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

The description is dense but every sentence is purposeful. It front-loads the primary purpose, then adds usage context, limitations, and alternatives without any 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?

Despite lacking an output schema, the description covers trigger conditions, why this tool exists, parameter behavior, limits, and alternatives. It is sufficiently complete for an agent to select and invoke the tool correctly in the intended scenarios.

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

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

Schema coverage is 100% and the input schema already describes all parameters, including 1-based/inclusive semantics and the 400-line cap. The description mostly restates these details (e.g., 'omit end for a 50-line window') rather than adding new parameter-level meaning, so a 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?

The description uses a specific verb+resource: 'Read an exact line range from a raw doc file by absolute line number.' It clearly distinguishes itself from siblings by being the 'windowed-read companion to grep_docs' and the ONLY way to read around hits in large data tables, making its purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: call read_lines when grep_docs returns a hit, and states it is the only way for certain large tables. It also names alternatives for other cases: get_document for prose .md files, grep_docs for searching values, and lookup_native for script natives.

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, which the description does not contradict. It adds substantial behavioral context: the hybrid fusion of vectors, full-text, and structured records; reranking; community findings merging by default; mode-specific retrieval semantics; and the return format (path, breadcrumb, heading, snippet, score). This goes well beyond the annotation.

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?

Although the description is long, every sentence earns its place. It is front-loaded with purpose and examples, then logically flows through modes, sibling routing, return format, filtering, and retry guidance. No filler or redundancy—the density is justified by the tool's complexity.

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 7 parameters (including a nested object), 3 enums, no output schema, and a complex retrieval behavior, the description covers everything an agent needs: return format, routing to get_document, mode semantics, category meanings, and retry guidance. It is fully self-contained 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 coverage is 100%, so the schema already documents all parameters. The description adds significant value: it explains the meaning of categories (cfx covers runtime/scripting API), the purpose of prior_attempt for retries, the difference between responseFormat modes, and gives examples. It also clarifies default limit rationale. This is far more than restating 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 opens with a clear, specific verb+resource statement: 'Search RedM/RDR3 docs by behavior, concept, or token' and gives concrete examples. It explicitly names sibling tools (lookup_native, asset_lookup, discovery_lookup, grep_docs) and the conditions that select them, making it impossible to confuse this tool with alternatives.

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

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

It provides explicit routing rules: when to use lookup_native, asset_lookup, discovery_lookup, and grep_docs, with specific conditions. It also explains mode selection (hybrid vs semantic vs lexical), category filtering, and the retry pattern with prior_attempt. No ambiguity about when to invoke 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 declare readOnlyHint=false and destructiveHint=false, and the description adds real behavioral context beyond them: findings are merged into default semantic_search results and retrievable via a category filter. It does not cover moderation, latency, or whether writes can be edited/removed, 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 purpose, then tightly organized into WHEN/WHEN-NOT bullets and a final authoring tip. Slightly long, but every line carries actionable information; 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 and none is needed, since the description explains the effect of a successful write (visibility to future agents). For a 5-param mutation tool with full schema coverage, everything an agent needs 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 100%, so baseline 3, but the description adds genuine authoring guidance beyond the schema ('Keep title short and searchable', body should explain WHY). Minor risk: it references `category: 'learnings'` for semantic_search while this tool's category enum has no such value, which could confuse an agent about valid values.

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 ('Share a verified finding back to the docs corpus') and states the downstream effect ('so the next agent can find it'), which distinguishes it from read-oriented siblings like get_document and 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?

Contains explicit WHEN and WHEN NOT sections with concrete triggers ('burned multiple iterations', 'undocumented quirk') and named alternatives to check first (semantic_search, grep_docs). Routing is unambiguous.

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