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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds only that the result is JSON scoped to one aspect; it says nothing about missing-record behavior, error cases, or payload shape for a network-backed lookup.

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 opening sentence is well front-loaded and the aspect list is useful, but the fragment "Lecturer aspect." is filler and several list entries restate the enum tautologically ("teaching-history — Get lecturer teaching history"). Roughly a third of the text adds no information.

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?

With two required params and full annotation coverage, the definition is callable as written, but with no output schema the description never indicates what an aspect payload contains (fields, pagination for portfolio aspects like karya/paten). An agent can invoke it but cannot anticipate result structure.

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 coverage is 50%: id_dosen is documented in the schema, but the aspect enum has bare values. The description compensates well by glossing each enum member in English (penelitian = research portfolio, pengabdian = service portfolio, karya, paten), which is real added meaning over the raw enum.

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 specific verb and resource ("Fetch one aspect of a single lecturer") and enumerates the seven aspects, so the agent knows exactly what it returns. It does not explicitly distinguish itself from siblings like get_university_lecturers or get_study_program_lecturers, which is the only missing piece.

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?

Usage is implied: fetch a single lecturer's detail by aspect, as opposed to the list-style siblings. There is no explicit when-to-use/when-not guidance and no mention that id_dosen must come from a prior search_pddikti call (that constraint lives only in the schema).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety and repeatability are covered. The description adds that the response is JSON and that no identifier is needed, but says nothing about how the shape differs per metric or about size/latency.

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?

Purpose and scoping constraints are front-loaded, and the long enum mapping is genuinely necessary given the unreadable metric codes. Minor waste remains in the dangling fragment 'Statistic metric.' and the repetition of 'Get ... count' phrasing across entries.

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?

With no output schema, the description should say more about what each metric returns — for example whether 'gender' or 'province' metrics yield multi-row breakdowns versus scalars. 'As JSON' alone leaves an agent unable to anticipate the response structure for grouped metrics.

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 enum values are opaque Indonesian abbreviations, so the description carries the full burden. It supplies an English gloss for every one of the 25 metrics, which is real added meaning, though a few glosses are terse and don't reveal what the output looks like.

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 gives a specific verb and resource ('Fetch one national aggregate statistic for Indonesian higher education as JSON') and pins the scope by ruling out single-institution queries. This clearly separates it from siblings like get_university and get_study_program, which operate on a specific id.

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?

It states when to use it ('country-wide counts') and when not ('not for a single institution'), and notes no id is required. It stops short of naming the specific sibling tools to use for institution-level data, so the routing hint is directional rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond them: that the record is public, that no listing exists, and that the return is JSON. It stops short of describing response shape or failure modes for an invalid/stale id.

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?

Three short sentences, front-loaded with the verb and resource, then the constraint, then the id-sourcing instruction. Every sentence carries load and none repeats the title.

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?

With a single required parameter, annotations covering the safety profile, and no output schema, the definition is nearly complete. The description hints at returned fields ('university, study program, enrollment status') rather than documenting them fully, which is the only remaining gap.

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 coverage is 100% and the schema itself already says the id is opaque and must not be guessed. The description reinforces provenance ('find the id with search_pddikti') but adds no new syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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 and resource ('Fetch the public PDDikti record of one student'). It also enumerates the content (university, study program, enrollment status) and explicitly distinguishes itself from list-style siblings with 'There is no student list', so an agent can tell it apart without opening the schema.

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?

Gives explicit routing: to obtain an id, use search_pddikti with entity "mhs" by name or NIM. Both the when-to-use condition and the required upstream step are stated, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds that each call returns exactly one aspect as JSON (a per-call granularity constraint), but says nothing about error behavior or what an unknown prodi id yields.

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 core purpose and the sibling redirect are front-loaded in the first two sentences. However, the dangling fragment "Study-program aspect." is redundant filler before the enum list, which is otherwise dense and useful.

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?

With no output schema and five aspects that each return a different shape (detail vs. counts vs. tuition range), the description never indicates what fields or structure to expect. Enough to invoke, but not enough to interpret results confidently.

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 coverage is 50% — id_prodi is documented in the schema, but aspect has no schema description. The description compensates by defining all five enum values, though several definitions are terse restatements ("detail — Get study program detail").

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 (fetch) and resource (one aspect of a single study program) and explicitly enumerates the five aspect values, so the agent knows exactly what the tool returns. It also names the sibling get_study_program_lecturers for the related-but-different roster data.

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?

Explicitly routes lecturer-roster needs to get_study_program_lecturers, which is a clear alternative/exclusion. It doesn't contrast with search_pddikti or get_university_study_programs, but the aspect enum effectively communicates what each call is for.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered structurally. The description adds only the return shape ('Returns a JSON list') and says nothing about pagination or result volume, which matters for an openWorldHint tool that could return long rosters.

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?

Front-loaded and short, but the sentence fragments 'Which lecturer set.' and 'Returns a JSON list.' read as dangling labels rather than clean prose, and the enum explanations arrive after them. Content is dense enough to justify the length, but the ordering could be tighter.

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?

No output schema exists, so the description does its job by stating the return is a JSON list and by pointing to get_lecturer for follow-up detail. The only real gap is unspecified pagination or result-size behavior for a potentially long lecturer roster.

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 coverage is 67%: id_prodi and semester are documented in the schema, but the `kind` enum has no schema description — the description supplies the meaning of both enum values, which is genuine added value beyond the schema. It adds nothing extra for id_prodi or semester, but none is needed.

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 and resource with explicit scope: 'List the lecturers attached to one study program in a semester.' The scope narrows it cleanly against the university-level sibling get_university_lecturers, and it names get_lecturer as the follow-up.

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?

Explicitly routes the agent: pass a returned lecturer id to get_lecturer for the profile, and disambiguates the two lecturer sets enumerated by `kind` ('dosen-homebase' vs 'dosen-penghitung-ratio'). This is exactly the when-to-use guidance the enum alone cannot convey.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds value annotations do not: the return type varies by aspect (JSON vs. raw image bytes for 'logo'), which materially affects how an agent handles the response. It does not mention rate limits or failures, keeping it short of a 5.

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?

Front-loaded with purpose, then routing, then the aspect legend, which is the right order. The fragment 'University aspect.' is redundant filler before the list, and the legend is dense but every entry carries distinct meaning.

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?

No output schema exists, so the description must convey return shape, and it does at a coarse level (JSON per aspect, image bytes for logo). Given eight aspects with heterogeneous payloads, it could say a bit more about what each aspect returns, but an agent has enough to select and invoke 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 coverage is only 50% and the enum values carry no per-value descriptions in the schema, but the description compensates fully by defining all eight aspect values (detail, rasio, mahasiswa, waktu-studi, riwayat, biaya-kuliah, fasilitas, logo). The id_pt constraint ('copied exactly from a search_pddikti result, do not guess') is in the schema and reinforced by the workflow implied here.

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 and resource ('Fetch one aspect of a single university ... as JSON, or its logo as an image') and scopes it to a single institution. It explicitly distinguishes itself from the two sibling tools an agent would most likely confuse it with.

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?

Gives explicit positive usage ('profile, accreditation, and history questions about one university') and explicit exclusions with named alternatives ('for its study programs or lecturers use get_university_study_programs or get_university_lecturers'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered; the description adds genuinely new behavior: per-program fan-out cost, cross-program merging and deduplication, and the return shape (JSON list). It stops short of noting pagination, error behavior for an unknown id_pt, or what happens when a program has no lecturers, which keeps it off a 5.

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?

Three sentences, zero waste, and the most decision-relevant facts are front-loaded: what it returns, then the cost, then the alternative. No restatement of the title or annotations.

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 two-parameter read tool with full schema coverage, rich annotations and no output schema, nothing an agent needs is missing; the fan-out warning and the sibling routing rule cover the only real failure modes (slow call, wrong tool).

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 coverage is 100% — both id_pt (with an explicit "do not guess or construct" warning) and the YYYYS semester pattern are fully documented in the schema. The description reinforces the scope of both parameters but adds no syntax or edge-case detail beyond it, so the baseline 3 applies.

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 and resource ("list all lecturers") plus scope (one university, one semester) and the aggregation semantics (merged across active study programs, deduplicated). It explicitly distinguishes itself from the sibling get_study_program_lecturers, so an agent can route between the two without opening either schema.

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?

Gives an explicit alternative and the condition that selects it: "prefer get_study_program_lecturers when one program is enough." The implied inverse — use this tool when the whole university is needed — is unambiguous, and the cost warning ("slower ... fans out one request per program") reinforces the trade-off.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds value beyond that by disclosing the return shape ('Returns a JSON list') and the intended downstream chaining, though it says nothing about result volume, pagination, or what happens when a university has no programs in that semester.

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?

Three short sentences, front-loaded with what is returned, followed by the follow-up call and the return type. Nothing is redundant and every sentence carries distinct information.

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?

With only two well-documented parameters and no output schema, the description adequately covers what the tool yields ('a JSON list' of programs with ids) and how to continue. It would be stronger if it hinted at the per-program fields beyond id or at empty-result behavior, but nothing critical for a correct call is missing.

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 100%: id_pt is documented as an opaque id copied from search_pddikti results and semester as a YYYYS pattern code. The description only reinforces the semester framing ('in one semester') and adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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 and resource ('List every study program (prodi) a university offered in one semester') and adds a scope qualifier (per university, per semester). It also distinguishes itself from the detail sibling by naming get_study_program as the follow-up for a single program's details.

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?

Gives a clear usage context — this is the listing step before calling get_study_program with a returned prodi id — which is explicit chaining guidance an agent can act on. It stops short of distinguishing itself from sibling listing tools such as list_study_programs_by_field or get_university, so no explicit exclusion is offered.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds a modest amount beyond that ('Returns a JSON list', 'Needs no id') but says nothing about result volume, completeness of the nationwide set, or ordering.

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?

Purpose and scope are front-loaded in the first sentence, and the enum glossary is dense but earns its space. Minor waste: 'field of study (bidang ilmu)' is restated as its own sentence, duplicating the opening parenthetical.

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?

A single-required-enum, read-only tool with a stated return type ('a JSON list') and every enum value translated. With no output schema, the description covers what an agent needs; only result shape detail would improve it marginally.

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 the parameter meaning and it does: it glosses the Indonesian enum terms in English (agama=religion, teknik=engineering, etc.), which the raw enum does not. It only falls short of 5 because the same single parameter is described twice.

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 and resource ('List study programs') plus a scope qualifier ('nationwide for one field of study') that implicitly separates it from the university-scoped sibling get_university_study_programs. It does not name a sibling outright, so it stops short of a 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?

'for discovering which programs exist in a discipline' and 'Needs no id' give a clear use context and implicitly contrast with the id-based lookup tools. No explicit when-not or named alternative, so it is clear context without exclusions.

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

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

Annotations already declare this as read-only, idempotent, open-world, and non-destructive. The description adds useful behavioral context by saying the result is a JSON list and is empty when nothing matches, though it does not discuss pagination or result limits.

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 short and front-loads the main instruction, the entry-point role, and the return shape. The trailing enum explanation is useful but slightly awkwardly appended.

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 two-parameter search tool with no output schema, the description provides the key context: what it returns, when to use it, and what the entity options mean. An agent has enough information to call it 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 coverage is only 50%, but the description compensates by explaining the 'entity' enum values: all, pt, prodi, dosen, and mhs. The keyword parameter is documented in the schema, so the combined description and schema give adequate parameter meaning.

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 specific verb and resource: search Indonesian higher-education records by keyword and return matching entries with opaque ids. It also distinguishes this as the entry-point tool, noting that every other tool needs an id from this search.

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?

It clearly explains when to use this tool first and why: every sibling get_* tool depends on ids returned here. It does not explicitly describe when not to use it, but the usage context is clear enough for an agent.

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