locate_usc_subject_codes

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows the operation is safe and non-mutating. The description adds minimal behavioral context, such as scope ('todos los grados actuales') and that it finds 'exact' codes, but does not disclose performance implications, pagination, or other runtime behavior. Given the annotation coverage, a 3 is appropriate as the description contributes some value but not rich detail.

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 a single, concise sentence that front-loads the core purpose. It contains no filler words and is easily parsed. However, it may be too terse, omitting essential details that could justify a slightly longer description, but as far as conciseness goes, it scores high.

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?

Given five parameters (two required), no output schema, and zero schema descriptions, the tool definition is dangerously incomplete. It does not explain what 'códigos G' are, how academic_year is used, what area_slugs or degree_urls filter, or what the output looks like. An agent has essentially no information to construct a valid request without external knowledge. The description is far from sufficient for correct invocation.

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 mentions only 'códigos G' implicitly referencing 'subject_codes', but does not explain any of the five parameters: subject_codes, academic_year, area_slugs, degree_urls, or concurrency. There is no guidance on required fields, formats, or how optional filtering parameters affect results. The description fails to add any meaning beyond what the bare parameter names convey, and even those names are not explained.

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 a clear action ('localiza') and a specific resource ('códigos G exactos en los planes oficiales de todos los grados actuales'). It distinguishes from siblings by focusing on exact G codes in all current degree plans, which is more specific than a generic degree list. However, it does not explicitly contrast with similar tools like list_usc_degrees or list_official_exam_subjects, leaving some ambiguity about when this tool is the right choice.

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 gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It simply states what the tool does without any context about use cases or when to prefer it over sibling tools. An agent would have no clue which tool to select for locating subject codes without opening schemas.

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