rt_get_notes

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that notes are returned 'newest first', which is a behavioral detail. However, it does not disclose whether this operation is read-only or destructive, or if it requires authentication, or if there are any side effects. For a simple 'get' operation, it might be safe to assume it's read-only, but the description doesn't explicitly state that. The lack of annotations means the description should have provided more safety context, but it does add the sorting behavior. Since it does not contradict annotations (none exist) and discloses a behavior, a 3 is reasonable. Adding 'read-only' or 'does not modify' would elevate it.

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 one sentence: 'Notes already on a candidate, newest first.' It is highly concise, front-loaded with the purpose, and includes a key sorting detail. No wasted words. Perfectly sized for a simple tool. This is a 5.

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 tool is simple: it retrieves notes for a candidate. With 2 params, no output schema, and no nested objects, the description is almost sufficient. It provides the sorting order. However, it lacks any information about the output format (though no output schema exists), and does not mention whether it returns all notes or if pagination is implied. Also, it doesn't clarify what 'notes' are in this system—are they internal notes? Since there is a sibling 'rt_add_note', it likely are notes added by users. The description could have added a bit more context about the notes' source or content, but given the simplicity, a 3 is appropriate. It gives the essential purpose and sorting, but lacks some depth.

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 for parameter documentation. It does not mention any parameters in the description: candidateId is required but its semantic is obvious from its name; limit is also self-explanatory as a numeric limit. The description does not explicitly state that candidateId identifies the candidate whose notes are retrieved, but that's implied by the tool name and description. Since there are only 2 parameters and both are fairly clear from their names, the description doesn't need to elaborate much. However, because coverage is 0%, the description could have added a sentence like 'Provide candidateId to fetch notes, and optionally set limit to cap the result count.' That would improve it. Given the simplicity, a 3 is acceptable.

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 states what the tool does: it retrieves notes for a candidate, sorted newest first. It clearly identifies the resource (notes) and the subject (candidate). It does not explicitly distinguish from siblings like rt_add_note or rt_get_candidate, but the verb 'get' and resource 'notes' are clear. Slight ambiguity: 'Notes already on a candidate' implies it's a read operation, but it doesn't explicitly say 'retrieve' or 'list'. However, the meaning is clear enough. Not quite a 5 because it doesn't differentiate from rt_get_evaluations or others that might also be about candidate details, but it's specific to notes.

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 does not provide explicit guidance on when to use this tool vs alternatives. It implies it is for reading notes, but without context on when to choose this over rt_add_note or rt_get_candidate. It lacks any mention of prerequisites, ordering, or alternatives. However, the tool name 'rt_get_notes' and description are self-explanatory enough for a simple read operation. A 3 is appropriate for a description that gives basic context but no explicit when-to-use alternatives.

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