mc_config

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

With no annotations, the description carries the full burden and does well: it discloses read vs write mode, that reads also return defaults, that patches are shallow-merged, that the config is session-scoped, and that mentionPatterns is configurable rather than hardcoded. It omits what happens to unknown keys, whether changes survive a reconnect, and any permission expectations.

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 read/write model and the no-params case, then layers examples and a practical tip. Slightly dense with two example payloads, but every sentence adds a fact an agent would otherwise have to guess.

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 2-param tool with nested free-form objects, no annotations and no output schema, the description covers the essentials: what reads return (current config + defaults), how writes are shaped, and how to reset. Persistence scope and error behavior on bad keys are the only real gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning for patch: dot-notation for nested keys, a worked example object, and the semantics of mentionPatterns as a list of learned nicknames. The reset parameter is left to the schema, which is acceptable since the schema documents it.

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 pair and resource: read/write this session's MC config, and enumerates the domains it covers (watchdog wake conditions, near radius, heartbeat interval, observation window, appellations). It does not name the sibling mc_admin_config, so an agent cannot tell from the description alone how session config differs from admin config.

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 no params = read-only view, pass patch = write, and gives a concrete situational trigger ('if "any player chat wakes you" is too noisy, set wakeOn.anyChat=false'). Missing is routing against the sibling mc_admin_config, which is the one alternative an agent would plausibly confuse this with.

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