DreamLand MUD

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds only 'in reading order for a newcomer' — a useful ordering hint but no info on the shape of the returned categories or error behavior for a bad key.

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

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

A single compact sentence plus a short follow-up; front-loaded with what is returned. Slightly elliptical ('Pass a key' — which key?) rather than wasteful.

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 with no output schema, the description should say enough about the returned list (are there many categories? does order matter for the agent's workflow?) and about the 'key' it references. It gives the gist but leaves the return shape and the help_list handoff underspecified.

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 100% schema coverage and an enum plus fallback rule documented in the schema, the baseline is 3. The description only gestures at how the result feeds 'a key to help_list' without explaining the lang parameter's effect on ordering or category names.

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 (categories of the help index) and the payload it returns (article counts, reading order for a newcomer). It is distinguishable from siblings like help_list and help_get, though it doesn't explicitly say how it differs from help_list — only that a key should be passed to 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?

Implies usage via 'Pass a key to help_list', which tells the agent this tool is an entry point feeding another. But there is no explicit statement of when to call this rather than help_list, help_search, or help_get.

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 as a read-only, idempotent, non-destructive tool. The description adds meaningful behavior beyond annotations: the Markdown return format, related-article links, and the exact keyword-resolution rules including fallback to best search hit.

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, front-loaded with the return format and then the resolution logic. Every clause carries useful selection or invocation information with no filler.

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

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

There is no output schema, but the description explains the return content as Markdown with related links. All three parameters are documented in the schema, and the description supplies the missing resolution behavior, so an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that id should come from help_search and by detailing how keyword matching behaves, which the schema only briefly hints at.

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

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

The description states a specific verb and resource: return the full text of one help article as Markdown, with links to related articles. It distinguishes the tool from help_search by explaining that its id comes from help_search, and from list/category siblings by focusing on fetching a single article.

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 gives two usage modes: pass an id from help_search, or pass a keyword. It also explains the keyword resolution order—exact title wins, shared keyword returns multiple articles to choose from, and anything else falls back to the best search hit—so an agent can predict outcomes before invoking.

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 read-only, idempotent, closed-world behavior, so the description needn't repeat safety details. It adds useful traits — result ordering by title and completeness of the listing — but says nothing about result size, pagination, or what an unfiltered call returns.

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

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

Two short sentences: the behavior first, then compact examples. No filler, nothing to cut.

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

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

All three parameters are enums and are covered, and with no output schema the sorting note is helpful. But the description is silent on the no-filter case (does it return all articles?) and on result volume, which matters for a list tool an agent may call broadly.

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

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

Schema coverage is only 33% (lang is the only described parameter), so the description carries the burden for category and kind — and it does, explaining the combination semantics and giving concrete example values. It still relies on the schema enums for the full value sets, which is acceptable.

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

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

States a clear verb+resource: enumerate every help article, optionally filtered by one category and/or one kind, sorted by title. Strong on scope, but does not explicitly contrast with siblings help_search or help_get, leaving the agent to infer the difference from names alone.

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 examples ("category 'classes'", "kind 'spell'", both) implicitly show how to use it and clarify the AND/OR combining logic. However, it never states when to prefer help_search or help_get over this tool, so guidance is inferred rather than declared.

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, closed-world behavior, so the description is free to spend its words on ranking semantics: exact keyword first, then title and keyword-prefix, then body text. That ranking order is genuinely useful for interpreting result order, though nothing is said about empty results or how many hits come back beyond the schema's limit.

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

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

Front-loaded with purpose, then ranking, then facet syntax, then the handoff to help_get — a sensible order. The facet list is long but earns its length because those tokens change invocation; only 'like in game' 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?

With no output schema, the note that it returns ids for help_get covers the return contract adequately for a search tool. The one real gap is the limit parameter, whose behavior and default of 10 are never addressed in prose.

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

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

Schema coverage is 67% and the weakest spot (limit) has no description anywhere, which the description also ignores. In exchange, it explains the query syntax in real depth — leading facet words (spell, skill, race, class, command, zone, religion, clan) plus RU/UA forms — which is semantics the schema does not carry.

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

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

States a specific verb+resource ('Find help articles') and immediately scopes how it matches (keyword, title, or article text), which cleanly distinguishes it from help_list and help_categories that do not search by text. An agent can tell what this returns without opening the schema.

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

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

The closing 'Returns ids for help_get' makes the follow-up workflow explicit and implies this is the entry point for lookup by content. It does not say when to prefer help_list or help_categories instead, so the routing against those siblings is left implicit.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real value on top: the world-reset-only scope exclusion and the sort contract ('by level, or by one bonus, highest first'), which affects how results should be interpreted. It stays silent on the default/variable result count and result ordering stability beyond the sort key.

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 data categories in the first clause, then adds scope and sorting constraints in two short sentences. Slightly dense prose with a long parenthetical subtype list, but no filler sentences.

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

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

For a 13-parameter read-only search with no output schema, the description covers the data domain, scope limits and sorting, which is enough to call it correctly; remaining details (level bounds, limit, include_limited, magic_type) are handled by the schema's enums and 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 high (69%) with enums on the key filters, and the description still contributes meaning beyond it: it clarifies that sorting can be by level or by a single bonus (highest first), distinguishing damage from stat bonuses. That matches the schema's sort semantics without contradicting them; with coverage this high the schema carries the enumerated 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?

The description enumerates the exact resource set (armor/gear, weapons, magic items listed by subtype, pets) and states what each result carries — stats, who may use it, source zone and mob. That is a specific verb-implied resource definition an agent can match to a user request 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?

One genuine usage constraint is given: 'Only items placed in the world by zone resets are listed', which tells the agent this won't answer questions about shop or quest-only items. There is no explicit when-to-use framing and no named alternative (siblings — help_*, news_*, who — are unrelated domains, so the cost is low).

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 the safety profile is fully covered. The description adds one genuinely new behavioral fact not in the schema: omitting id silently defaults to the newest post, which is important to know. It says nothing about invalid-id handling or return shape, so it adds value without being rich.

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

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

Two short sentences with no filler. The core purpose is front-loaded and the parameter guidance and default behavior follow in the order an agent needs them.

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-optional-parameter read tool with no output schema, the description covers purpose, input source, and default behavior — enough to call it correctly. The only real gap is error behavior for an unknown id, which is minor at this complexity.

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

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

Schema coverage is 0%, so the description carries the full burden for the single parameter, and it does: it identifies where the id comes from (news_list) and what happens when it is omitted, which the bare integer schema cannot convey. It does not mention that id must be a positive integer, but the source hint is the higher-value information.

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 the resource and scope precisely: 'the full text of one news post,' which distinguishes it from the sibling news_list that returns many. It is a noun phrase rather than a verb-led statement, but the read intent is unmistakable and the singular-vs-list contrast with news_list does the differentiation work.

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

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

Explicitly routes the agent: 'Pass the id from news_list,' naming the sibling that produces the input. It also states the no-argument path ('without one, the newest post'), so both call modes are covered. It stops short of stating when-not to use this tool, but the context 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 read-only, idempotent, non-destructive, non-open-world. The description adds meaningful context beyond that: default newest-first ordering, that results are summaries (id, date, author, subject) rather than full text, and the language caveat about content mix.

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 what the tool returns, then filtering semantics, then the language caveat and sibling pointer. No filler.

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

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

With no output schema, the description correctly enumerates the returned fields and warns that full text requires news_get. Only the limit parameter's behavior (paging/top-N) is left implicit, which is a minor gap for a two-parameter list tool.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains the query's AND semantics across subject and text, which is real added value. The limit parameter is left unmentioned, though the schema's default and 1-50 range partially compensate.

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 ('Game news posted by the immortals, newest first') and enumerates the fields returned, so the agent knows exactly what this lists. It also explicitly points to news_get for single-post reads, distinguishing it from 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?

Explicitly routes to news_get for reading a full post, and explains what the query parameter does at a semantic level (all-words matching over subject and text). No explicit when-not-to-use case is given, but the list-vs-get split 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 destructiveHint=false, so safety is covered. The description adds meaningful context beyond them: the data is live ('right now'), which explains idempotentHint=false, and it notes output parity with the game's Discord bot, setting expectations about content and presentation.

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

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

Three tight sentences, with the default no-argument behavior front-loaded before the name-based variant. The closing Discord-bot comparison earns its place as a mental model, though it is the least essential sentence.

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 burden of describing returns and does so by enumerating the data fields for both modes. It stops short of describing response structure or formatting, but an agent has enough to call it correctly and anticipate what comes back.

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, setting a baseline of 3. The description goes further by explaining what supplying `name` actually changes in the response (race, clan, clan rank, remorts, online status), which is behavioral meaning the schema does not convey. `lang` is left entirely 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 names the exact resource (characters online, Discord bridge users, weekly peak/uniques) and clearly describes the second mode triggered by a name. An agent can distinguish this from every sibling (help_*, item_search, news_*) 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?

It states the branching condition explicitly: omit the name for a live roster, supply a name for a single character's race, clan, clan rank and remorts regardless of online status. There are no competing alternatives among siblings, so the lack of an explicit 'when not to use' is a minor gap.

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