add_diagram_note

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Add a text note to a diagram' and 'Phase B stub.' It does not describe side effects, requirements, return behavior, or any constraints. The 'stub' hint is about implementation status, not tool behavior. This is essentially a restatement of the name with no added 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 (one sentence) and lacks any structure such as bullet points or sections. While conciseness is good, this is under-specification rather than efficient writing. The 'Phase B stub' adds little useful structure. It is not verbose, but it fails to convey essential information in an organized way.

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 tool with 4 parameters, 2 required, and an output schema, the description is severely incomplete. It does not explain what a text note is, how it is placed on a diagram, what the output represents, or any constraints. With no annotations to supplement, the description leaves the agent with insufficient context to use the tool correctly.

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%, so the description must compensate by explaining parameter meaning. It does not mention diagram_id, text, x, or y at all. The description adds zero value beyond the schema's property names and types. Given the complete lack of parameter guidance, this score is appropriate.

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 action: adding a text note to a diagram. It uses a specific verb and resource, and distinguishes itself from siblings like add_symbol (which adds symbols) and create_element. However, it lacks any detail about what a 'text note' entails or how it differs from other annotation tools, so it is not a perfect 5.

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?

There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, scenarios, or exclusions. The description simply states what it does, leaving the agent to infer when it is appropriate. This is a significant gap for a tool with many siblings.

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