Nightbreak Forge

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is well covered. The description adds the 'mirrored repo' context and hints that large files support slicing, but says nothing about rate limits, file-size caps, or error behavior on missing paths.

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, front-loaded with the core action and followed by the useful slicing caveat. 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?

For a simple read tool with full annotations and rich schema examples, this is close to complete. The absence of an output schema means the description could clarify return shape (raw file text vs metadata), a minor remaining gap.

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

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

Schema coverage is 75%, so the schema documents most params including the repo enum and path example. The description's line-slicing mention aligns with line_start/line_end but adds no syntax or edge-case detail beyond the schema; baseline 3 applies.

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

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

States a specific verb (fetch) and resource (a file from a mirrored plugin source repo), and the line-slicing note clarifies the scope. It distinguishes itself from search_plugin_source by targeting a known path rather than searching, though it doesn't explicitly name that 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?

Usage is implied: you call it when you know the repo and path. There's no explicit 'use this instead of search_plugin_source' guidance or prerequisites, leaving the agent to infer when to fetch versus search.

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 this is a read-only, idempotent, non-destructive, closed-world call, so the bar is lower. The description still adds real value beyond them by documenting the failure mode: a missing page returns `suggestions` containing the closest existing pages, which no annotation or schema conveys.

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

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

Three short sentences, front-loaded with the action and resource, followed by usage routing and the error behavior. No boilerplate or repetition of the schema.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description covers purpose, name-sourcing, and error recovery. The only minor gap is that the returned content's format (e.g., markdown vs. plain text) and size/pagination characteristics are not stated.

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 single `path` parameter is fully documented with examples, so the schema does the heavy lifting. The description adds the useful nuance that page names are unstable and should be sourced from search results, but no additional syntax or format detail beyond that.

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

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

The description names a specific verb pair ('fetch and extract readable content') and a specific resource ('a specific Nightbreak wiki page'), with a concrete example path. It is clearly distinguished from its sibling search_wiki, which is named as the source of page names rather than a competitor.

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 page names must be taken from search_wiki results, which routes the agent correctly between the two discovery vs. retrieval tools. It stops short of an explicit exclusion such as 'do not use this when you only have a topic name', but the context is clear enough.

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

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

Annotations already establish that this is a safe read-only, idempotent, closed-world operation, so the description only needs to add context. It adds a useful behavioral norm ('read it once before writing files'), implying static reference content rather than live state, but says nothing about size, pagination, or how the notes are organized.

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 sentences, front-loaded with the core content scope and ending with the actionable directive. The middle content list is dense and comma-heavy but each item signals real content an agent might need.

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 safety, the description's main job is to say what the notes contain and when to read them, which it does. Only minor gaps remain, such as how the notes are structured or whether any section is authoritative over 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly does not invent parameter guidance.

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

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

The description names the resource (authoring notes: per-type file locations, plugin rules, boss/combat AI notes, Lua hook reference), so an agent can tell roughly what it returns. But the head is a noun phrase ('Where each config type's files go...') rather than a clear verb+resource statement, and the listed 'Lua hook quick reference' overlaps with the sibling get_local_lua_reference, blurring the distinction.

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

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

The closing clause 'Read it once before writing files' gives an explicit trigger condition for calling the tool. It does not name alternatives (e.g., get_local_lua_reference for Lua details, get_config_schema for schemas), so routing between siblings 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description supplies a genuinely non-obvious behavioral trait beyond that: long option lists are truncated in normal output, with a documented workaround. It does not mention whether results are scoped to a plugin/version context or cached.

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 sentences, both load-bearing: the first defines the payload, the second discloses truncation and the remedy. Front-loaded with the return shape and no redundant restatement 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 no output schema, the description carries the return-shape burden and does so by listing the fields returned plus the truncation caveat. It leaves the sequencing relative to list_config_types and validate_config_files implicit, which an agent would need to work out from the sibling descriptions.

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. The description adds meaning by linking the truncation behavior to the `field` parameter: passing field returns that single field with every allowed value, which explains *why* the parameter exists rather than just what it accepts.

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 resource and verb: returns one config type's fields as Forge edits/validates them, and enumerates the returned attributes (key, value type, default, required, description, allowed values). It never explicitly contrasts with list_config_types, which the schema references, so sibling differentiation relies on the reader inferring it.

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 second sentence clearly explains the `field` escape hatch for full option lists, implying 'use field when you need all values.' There is no explicit when-to-use statement versus list_config_types (discovery) or validate_config_files (checking), so the agent must infer the workflow.

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, idempotentHint, destructiveHint=false, so the safety profile is covered. The description adds useful context — that the reference reflects what 'the editor currently knows about' and that references are type-partitioned rather than universal — but says nothing about size, format, or how to detect an unknown type.

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 script_type instruction are front-loaded and every sentence is load-bearing. The parenthetical per-type details make it denser than ideal, but the content is necessary routing 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 parameterless-default reference lookup with no output schema, the description tells the agent what each call will return (that type's hooks and context.* namespaces) and how to avoid cross-type confusion. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description meaningfully enriches script_type by mapping each enum value to a concrete script location and API surface — far more than the schema's one-line default note. scope semantics are largely 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?

States a specific verb and resource ('Read the ... local Lua validator/editor reference') and enumerates exactly what it contains (hooks, fields, methods, exact values, handle helpers). It is clearly distinct from siblings such as validate_lua_power_draft or fetch_wiki_page.

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: 'Pass script_type matching the file you are working on', names each type with the directory/file it maps to, and warns that the boss reference does NOT contain NPC/FMM/Mind/enchantment APIs. The when-to-use condition is spelled out 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?

The annotations already declare the operation as read-only, idempotent, non-destructive and closed-world, so safety behavior is covered. The description adds useful scope and output context by naming the returned fields and explaining how the type is reused downstream.

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 tightly written sentences with no wasted words. The returned resource and its downstream use are front-loaded and easy for an agent to scan.

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

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

For a simple read-only list tool with full schema coverage and no output schema, the description is complete. It even enumerates the returned fields, compensating for the absence of an output schema.

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

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

Schema description coverage is 100%, and the single optional plugin filter is documented in the schema. The description does not add filter-specific semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states exactly what the tool returns: config file types known to Forge for released plugins, including plugin, label, server path, format and wiki page. It also clarifies how the returned type is consumed by get_config_schema and validation workflows, which distinguishes it from sibling 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?

It gives clear downstream usage: pass a returned type to get_config_schema or use it as a validation path. It does not explicitly compare all alternatives or state exclusions, but the intended workflow is evident.

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, idempotent, non-destructive), so the description is correctly focused on adding domain context: it explains that the index spans six mirrored repos, that MagmaCore is the shared-core layer, and that FMM has plugin-specific tables. It does not describe result shape (snippets, line numbers, match context) or what happens when max_results truncates, which is a real gap for a search tool.

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

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

The core purpose and the default behavior lead, followed by repo-specific guidance that earns its place because it changes how the agent scopes a query. Slightly dense and the MagmaCore sentence is a bit padded with parenthetical examples, 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 five-parameter read-only search tool with full schema coverage and no output schema, this covers scope, defaults, and cross-repo reasoning well enough to invoke correctly. Only the return shape and truncation behavior remain unstated.

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

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

Schema description coverage is 100%, so the schema already documents mode, query, repos, max_results, and path_prefix in detail. The description only restates the default (every repo, file content grep), which is useful reinforcement but adds no syntax or formatting guidance beyond the schema. Baseline 3 applies when the schema carries parameter semantics.

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

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

States a specific verb (search) and a precisely enumerated resource set (EliteMobs, MagmaCore, BetterStructures, FreeMinecraftModels, CannonRTP, ResurrectionChest) plus the default mechanism (content grep). It is clearly distinguishable from the sibling fetch_plugin_source_file, which retrieves a file rather than searching across repos.

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 this BEFORE answering plugin-specific questions or generating Lua/YAML files" gives an explicit usage trigger, and the description tells the agent when to reach for MagmaCore (shared core helpers) and FreeMinecraftModels (its own LuaItemTable/LuaPropTable) specifically. It stops short of saying when to prefer the sibling fetch_plugin_source_file once a hit is found, so no true alternative routing is given.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real behavioral context beyond them: word-based case-insensitive matching, ranking order, and the handoff field `page` for the follow-up fetch. It stops short of saying how many results exist or how paging beyond max_results works.

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 core action, then matching/ranking semantics, then the routing rule. No filler and no repetition of schema fields.

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

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

For a two-parameter, read-only search tool with rich annotations and no output schema, the description covers purpose, matching behavior, result handoff and the sibling boundary. Only minor gaps remain, such as whether results are truncated or ordered deterministically beyond the stated ranking.

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

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

Schema coverage is 100%, so both parameters are already documented with examples. The description still adds meaning beyond the schema by explaining how the `query` string is matched (word-level, case-insensitive) and ranked, which directly informs query formulation.

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 the Nightbreak wiki for relevant pages and snippets") and even discloses the ranking basis (title, page name, body). It is clearly distinguishable from the sibling search_plugin_source, which it names explicitly.

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

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

Gives an explicit when-to-use ("high-level docs, examples, and tutorials") and a when-not with the named alternative ("not for symbol verification — use search_plugin_source"). It also routes the follow-up step by telling the agent to pass the `page` value to fetch_wiki_page.

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, idempotent, non-destructive behavior, and the description reinforces that with "Nothing is stored" while adding genuinely new facts: the 50-file-per-call cap and the crucial workspace scoping rule that "not found" means not present in this call, not absent from the server. It does not describe the shape of the validation report, which is a remaining gap.

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

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

Front-loads the verb and resource, then layers the constraints in descending importance. It is a single dense paragraph with some embedded parenthetical examples, but no sentence is 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 one-parameter, stateless validation tool with no output schema, the description covers inputs, limits, and the semantics of a not-found result. The only real omission is what a returned validation report contains (error list, severities), which an agent would want before parsing results.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining why `path` matters (it determines the file's type), giving a concrete example path, and clarifying that the `files` array is a single coherent set whose members cross-reference each other.

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 ("Validate plugin config files (YAML and Lua)") and enumerates the checks performed: required fields, allowed values, plugin rules, Lua analysis, and cross-file references. It is clearly distinct from the fetch/search siblings, but it never distinguishes itself from `validate_lua_power_draft`, whose scope (Lua analysis) visibly overlaps.

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 operational guidance: send every file with its full server path so the type can be inferred, batch related files together because cross-references resolve only within the sent set, and stay under 50 files. It stops short of naming an alternative tool or stating when to prefer `validate_lua_power_draft`.

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, idempotent, non-destructive), and the description goes beyond them to disclose a concrete failure mode: passing the wrong script_type yields false-positive errors, illustrated with hook-name examples (on_right_click vs on_npc_interact). That is real behavioral context an agent cannot get from 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 the core action and the IMPORTANT callout before the per-type enumeration. The lengthy list of script types partially restates the schema enum, making it denser than strictly necessary, but each clause carries actionable mapping information.

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

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

For a read-only validator with no output schema, the description covers what to pass, when, and the dominant failure mode. It doesn't say what the validation response looks like (error list shape), which is the remaining gap, but everything needed to invoke 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 would be 3, but the description adds genuine meaning beyond the enum: it maps each script_type to its directory (powers/, scripts/, npc_scripts/, behaviors/, pet_behaviors/, enchantments/) and the fmm:pet/<file> id form. Minor duplication of the enum list, but the error-consequence framing is added value.

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

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

States a specific verb (validate) and resource (draft Lua script against the local Nightbreak Forge validator), and its timing/purpose (before finalizing generated Lua files). It is clearly distinguishable from the sibling validate_config_files, which targets configs rather than Lua scripts.

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 when to use it ('before finalizing generated Lua files') and what it catches (unknown helpers, invalid fields, malformed structure). It does not name sibling alternatives like validate_config_files, so it stops short of full when-not routing, but the usage context is unambiguous.

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