get_vocab_notes

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds nothing beyond them: no indication of what happens when the vocab does not exist, whether an empty note set is returned, or anything about the note payload. With annotations covering the basics, a low score is still warranted for the near-total absence of added 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?

One sentence, front-loaded with verb and resource, and the identifier-form hint is packed in at the end with no filler. Appropriately sized for a simple single-parameter getter, though it is terse to the point of omitting useful detail.

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 read-only single-parameter getter with no output schema, the description covers the core call but omits failure behavior for an unknown slug/ID and gives no sense of what 'notes' contains. Adequate as a minimum-viable definition, not complete.

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 carry parameter meaning, and it partially does by noting the identifier can be a slug or an ID. It does not clarify format, case sensitivity, or whether a numeric ID string is acceptable, so the compensation is only partial.

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?

States a specific verb ('Get') and resource ('notes') scoped to a vocabulary item, which is enough to separate it from get_vocab (the item itself) and get_vocab_neighbors. It does not explicitly name the sibling it is not, so a 5 would require that differentiation.

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 'by slug or ID' phrase implies the lookup forms available, giving indirect guidance on how to call it. There is no explicit when-to-use, when-not-to-use, or reference to an alternative sibling such as get_vocab, so usage is only inferable.

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