mdshare

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

The description adds valuable behavioral context beyond what annotations provide. While annotations indicate destructive (true) and non-idempotent (false) operations, the description clarifies this is a 'full replace' operation, explains permission requirements, specifies parameter precedence rules ('file_path wins'), and mentions version history implications compared to patch_document. 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 efficiently structured with front-loaded key information (purpose and permission requirements), followed by parameter guidance and alternative tool recommendation. Every sentence adds value without redundancy, making it easy for an agent to parse and apply.

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 mutation tool with rich annotations but no output schema, the description provides strong contextual completeness. It covers purpose, permissions, parameter usage, alternatives, and behavioral implications. The only minor gap is lack of explicit information about return values or error conditions, but this is mitigated by the comprehensive parameter guidance.

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 description coverage, the baseline is 3, but the description adds meaningful context about parameter usage: it explains when 'key' is optional, provides guidance on choosing between 'file_path' and 'content' based on file location and size, and clarifies the 'author' parameter's purpose for attribution. This goes beyond the schema's technical 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 the tool's purpose with specific verb ('update'), resource ('existing mdshare document'), and scope ('full replace'). It distinguishes from sibling tools like 'patch_document' by specifying this is a full replacement rather than incremental editing.

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 guidance on when to use this tool vs alternatives: 'PREFER file_path over content for files already on disk' and 'For small edits to large documents, consider patch_document instead.' It also specifies permission requirements ('Requires edit or admin permission') and contextual conditions for optional parameters.

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