external.library_add

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

No annotations are provided, so the description carries the full burden. The description merely states the action without disclosing whether the operation is destructive (e.g., overwriting existing library with same name), requires network access, modifies persistent state, or is reversible. For a creation/mutation tool with no annotations, the description is severely lacking in behavioral context.

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 extremely short (3 words), which initially suggests conciseness. However, it is under-specified to the point of being almost tautological—'Add external library' could be inferred from the tool name. While there is no wasted text, the description fails to earn its place because it does not supply information that the agent couldn't already 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?

Given the large sibling set with many library-related tools, the complexity of this operation is high, but the description provides almost no completeness. There is no output schema, so the return value unspecified. The agent has no guidance on required parameters (beyond the schema's required list), effects on state, or interaction with sessions. A tool with 3 parameters (especially the opaque 'auto' boolean) and zero schema descriptions demands far more detail.

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 0%, meaning the schema provides no human-readable descriptions for any of the 3 parameters. The tool description mentions no parameters at all, so it adds zero meaning beyond what is in the raw schema (parameter names and types only). The agent has no idea what 'auto' means, how 'session_id' is used, or what format is expected for 'name'. This is a significant gap.

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 says 'Add external library.' This is a clear verb+resource pair indicating a creation operation. However, it does not distinguish itself from siblings like 'external.library_remove' or 'external.library_list' beyond the action verb, and it does not specify what an 'external library' is in this context. The purpose is minimally clear but lacks specificity about the scope or type of library.

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?

No guidance is provided on when to use this tool versus alternatives such as 'type_library.create' or 'type_archive.create', which sound conceptually similar. There is no mention of prerequisites (e.g., whether a session must be open) or hints that the tool is specifically for external libraries (e.g., from a third party) versus user-defined type libraries. The usage context is left entirely to the agent to infer.

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