tag

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

No annotations are provided, so the description carries the full burden. It discloses that add/remove modify tags and list/select are read-only. However, it does not mention permissions, error conditions, or side effects beyond tag changes. This is adequate for a straightforward tag management tool.

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 concise and well-structured: an overall purpose sentence, then bulleted actions and their requirements, followed by a clear list of arguments. Every sentence adds value without redundancy.

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?

The description covers all four actions and their parameter needs. An output schema exists, so return values don't need explanation. For a tool with 5 parameters and moderate complexity, the description is complete and sufficient.

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%, and the description compensates fully by explaining each parameter's purpose, format (e.g., 'Comma-separated tags'), and when they are required. It also provides examples for tags and query, adding significant value beyond 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 clearly states 'Manage notebook tags and find relevant notebooks by tag matching,' specifying verb and resource. It lists four distinct actions (add, remove, list, select) which differentiate it from sibling tools like notebook_create or source_add that handle other resources.

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 explains when each action is appropriate and which parameters are required per action (e.g., add/remove require notebook_id and tags; select requires query). It does not explicitly state when not to use but provides clear context for each operation.

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