mediawiki_apply_formatting

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

The description adds significant behavioral context beyond the annotations (which only indicate destructiveHint). It explains the preview behavior ('Set preview=false to apply'), authentication requirements ('Requires authentication (bot password)'), and return details (revision ID, diff URL, undo instructions), providing a thorough understanding of tool 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 well-organized into clear sections (BEST for, USE WHEN, NOT FOR, PARAMETERS, RETURNS, NOTE) with front-loaded key information. Each sentence serves a purpose without redundancy, achieving high conciseness while covering essential 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?

Given the tool's complexity (7 parameters, destructive action, authentication need), the description covers preview behavior, authentication, return values, and examples. However, it omits explicit mention of the 'rationale' parameter, which is a required input. The existence of an output schema is implied but not explicitly described, leaving a minor gap.

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

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

Schema description coverage is 100%, but the description adds value by providing concrete examples for the 'format' parameter (e.g., 'bold: \'\'\'text\'\'\''), clarifying default behavior for 'all' and 'preview', and detailing 'preview' and 'summary'. However, the 'rationale' parameter is not explicitly discussed in the description, slightly limiting completeness.

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 'BEST for adding formatting markup to specific text,' providing a specific verb and resource. It lists concrete examples of user requests (e.g., 'strike out X') and distinguishes from sibling tool mediawiki_find_replace, making the purpose 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 explicitly states when to use the tool with a 'USE WHEN' section and provides specific examples. It also includes a 'NOT FOR' section that identifies an alternative tool (mediawiki_find_replace) for replacing text, offering clear guidance on when not to use this tool.

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