manage_tag

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

With no annotations, the description carries the full behavioral burden and does well by identifying which actions are writes, describing the HTTP endpoint patterns, and stating the return dict shape. It does not mention permissions, authentication, or cascading effects of deletion, but the core write/read behavior is transparently disclosed.

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 summary sentence is front-loaded, followed by tight behavioral details and a structured Args/Returns layout. Despite being longer than typical descriptions, each sentence contributes needed information and there is no filler or repetition.

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 5-parameter CRUD tool with no output schema and no annotations, this description covers all invocation scenarios, parameter semantics, return shape, and even cross-object guidance about tag_list. An agent has enough context to select and call the tool correctly without opening sibling definitions.

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%, yet the description's Args section compensates fully: it defines the allowed action values, when handle is required, what data contains, the optional nature of query, and the instance default from get_instances. Every parameter is given meaning beyond its bare type in 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 opens with 'Create, read, update or delete Gramps Tag records,' a specific verb-resource pairing that immediately distinguishes it from the many manage_* siblings such as manage_person and manage_source. The added note that tags are 'lightweight labels attachable to any object' further clarifies the resource's role.

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?

Action-specific usage is explicit: get lists tags when handle is empty or returns by handle, create requires a name, update PUTs data, delete removes by handle. It also gives cross-context guidance ('To tag an object, reference the tag handle in that object's tag_list'), though it does not explicitly state when not to use this tool versus other manage_* siblings.

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