AIOS Public Discovery

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

The description adds real behavioral context beyond the annotations: the call is free and produces no product result, which tells the agent it can be used cheaply for probing. Annotations (readOnlyHint=false, openWorldHint=false, destructiveHint=false) cover the safety profile, though readOnlyHint=false sits in mild tension with a 'Return ... state' framing; this is most likely a conservative default rather than a claimed mutation, so it is not scored as a contradiction.

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?

Two short sentences, front-loaded with the purpose and followed by the cost/effect caveat; nothing is padded. The only cost is that the second clause ('no product result') is cryptic without further context.

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 an output schema present, return values need no explanation, and zero parameters keep the calling surface simple. What is missing is sibling routing — an agent cannot tell from this description why it would call aios_status instead of check_guidance_status or preflight_request.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Schema coverage is 100% and the empty object schema is self-explanatory.

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 verb+resource ('Return public AIOS discovery state'), so the agent knows it retrieves some status/discovery payload. However, 'AIOS discovery state' is internal jargon and does not distinguish this tool from siblings such as check_guidance_status, preflight_request, or list_pricing, leaving the agent to guess which status tool it needs.

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?

'Free; no product result' hints at the cost model and that this is a lightweight probe rather than a work-producing call, which is genuinely useful. But it never states when to choose this over check_guidance_status or preflight_request, and offers no exclusions or prerequisites.

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 destructiveHint=false and openWorldHint=false, and the description usefully adds cost ('Free') and output scope. However, readOnlyHint=false is at odds with the purely informational framing ('Returns current preserved verification status'), and the description never explains what the non-read-only aspect is, nor mentions caching or rate limits on the freshness check.

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?

Two sentences, both load-bearing: one for when to call, one for what comes back plus cost. It is front-loaded with the trigger condition and contains no filler or restatement of the tool name.

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?

An output schema exists, so return-value detail is legitimately omitted, and the description covers timing, scope and cost for a one-optional-parameter tool. The remaining gaps are the ID format for source_id and the unexplained non-read-only annotation, both minor.

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 0% and the single parameter is a bare string with an empty default, so the description carries the burden. It does add real meaning by saying the call covers 'one or all monitored sources', implying source_id is an optional filter, but it gives no hint about the expected ID format or where to obtain valid IDs.

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 second sentence states a specific verb and resource: returns verification status, freshness and provenance for monitored guidance sources, scoped to 'one or all'. That is concrete enough to distinguish it from siblings like get_guidance_changes or list_guidance_sources, though it never names or contrasts those siblings explicitly.

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?

'Use before answering or acting when current official GOV.UK employment guidance materially matters' gives a clear triggering condition, which is unusually good for a status tool. It stops short of naming when-not-to-use or pointing to an alternative (e.g. get_verification_evidence for deeper evidence), so it is not a full 5.

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?

The description adds one genuinely useful behavioral fact beyond the annotations: the call is 'Free', a cost signal absent from the structured fields and relevant given the sibling list_pricing. It does not, however, describe error behavior for unknown or non-public IDs. Note the mismatch between the 'get/describe' framing and readOnlyHint=false, though this is an annotation oddity rather than a direct contradiction.

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?

Two short sentences, front-loaded with the action and target; nothing is wasted. The trailing 'Free.' is slightly clipped in tone but does carry information, so the brevity is mostly earned rather than merely terse.

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?

An output schema exists, so return values need not be described. However, for a lookup tool the critical missing piece is where a valid capability_id comes from and how it relates to list_capabilities, which the description never supplies.

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 single required parameter capability_id gets no explanation in the description — no format, no example, no pointer to where IDs come from (e.g. list_capabilities). With one undocumented parameter, the description fails to compensate for the coverage gap.

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 ('Describe') and a specific resource ('one stable public AIOS capability ID'), which clearly distinguishes a single-ID lookup from the sibling list_capabilities. The qualifiers 'stable' and 'public' also narrow the scope of what IDs are valid, though the sibling distinction is left implicit rather than named.

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?

'one ... capability ID' implies this is the single-item lookup in contrast to list_capabilities, but the description never says when to prefer this over the list tool, nor what to do if the ID is unknown. Usage is inferable from the phrasing rather than stated.

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 declare readOnlyHint=false and openWorldHint=false, so safety characteristics are already partly covered. The description adds the useful cost trait ('Free') and clarifies the comparison scope (retained vs. latest preserved state). It does not disclose whether the call can mutate anything despite readOnlyHint=false, which is a notable omission for a get-prefixed tool.

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 the usage trigger, with no filler. It is appropriately sized, though the terse phrasing leaves the purpose statement implicit rather than stated outright.

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?

An output schema exists, so return-value explanation is not required. But the description is silent on how to obtain a valid source_id and on how this tool relates to check_guidance_status, which are the two things an agent most needs 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 description coverage is 0% and the single parameter 'source_id' has no title or description in the schema. The description never mentions source_id, how to obtain it, or its format, so it fails to compensate for the coverage gap. A sibling like list_guidance_sources would presumably supply valid IDs, but no link is made.

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 names the specific resource (monitored official UK employment guidance) and the specific question it answers (whether/what changed, and whether earlier retained guidance differs from the latest preserved state). It is clear about what is returned, though it never states a verb like 'returns' and does not differentiate itself from the close sibling check_guidance_status.

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 gives an explicit trigger condition: 'Use when the task asks whether... guidance changed, what changed, or whether earlier retained guidance differs.' That is a clear when-to-use signal. However, it names no alternatives or exclusions, so the agent must guess how this differs from check_guidance_status or get_verification_evidence.

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 only declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, which conveys little about content; the description adds meaningful behavior beyond them: the result is bounded, includes verification time and provenance, comes from a monitored GOV.UK source, and the call is Free. It still omits rate limits or failure behavior, but for a single-read evidence tool this is solid 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 dense but well front-loaded sentence; the use condition leads and the return contents and cost follow. The trailing "Free." fragment is terse but earns its place as a cost signal.

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?

An output schema exists, so explaining return values is optional and the description still does so helpfully. The real gap is the undocumented required source_id and no pointer to the sibling tool that would supply it, which an agent needs in order to call this successfully.

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 for the single parameter is 0% and the description never mentions source_id, its format, or where an agent obtains a valid value (e.g., from list_guidance_sources). With low coverage the description is expected to compensate, and it does not.

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 names the resource (verification evidence from a monitored GOV.UK employment source) and enumerates what comes back: source identity, verification time, provenance, and a bounded excerpt. It is clear what the tool retrieves, though the verb is implied by the name rather than stated, and it does not explicitly distinguish itself from siblings like get_capability or list_guidance_sources.

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?

"Use when an agent needs evidence for a consequential answer" gives a concrete triggering condition tied to answer stakes. It does not, however, state when NOT to use it or name an alternative tool for less consequential lookups.

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 declare destructiveHint=false and openWorldHint=false, but notably readOnlyHint=false for what is plainly an enumeration call, and the description does not reconcile that. It does add one behavioral fact not present in annotations — that the call is free — plus the "public" visibility scope.

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?

Two short sentences with the core action front-loaded; nothing is padded. The "Free." fragment is terse but carries genuinely useful cost information rather than filler.

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 zero-parameter, read-oriented listing tool with an output schema present, the description covers what it returns conceptually (capabilities and their availability) and adds the cost model. Only the routing relationship to sibling tools is left unstated.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No parameter guidance is required or expected 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 clear verb+resource ("List ... capabilities") with scope qualifiers ("public", "availability"). It is distinguishable from get_capability (singular, detail fetch) and list_pricing, but the description never names or contrasts those siblings explicitly.

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?

No when-to-use or when-not-to-use guidance is given. The reader must infer that this is the discovery/enumeration entry point versus get_capability for a single item; the word "Free" hints at a cost model but not at tool selection.

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 declare openWorldHint=false and destructiveHint=false, so the safe/closed-world profile is already covered. The description usefully adds "Free" and the scope boundary, but it never addresses the odd readOnlyHint=false annotation (a listing call that the server flags as not read-only), which is exactly the kind of behavior an agent would want clarified.

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 usage trigger and ending with a useful cost cue ("Free"). Every sentence carries information, though the legal-advice disclaimer is boilerplate that slightly dilutes the core message.

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?

An output schema exists, so return values need not be explained, and the description covers scope, exclusions, and timing adequately for a zero-argument discovery tool. The only unaddressed item is the readOnlyHint=false annotation, which leaves a small gap in behavioral completeness.

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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. No parameter-related information is missing or misleading.

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 clear verb+resource ("Lists only the monitored GOV.UK source set") and narrows the domain to UK employment-guidance classes verified by G05. It partially differentiates from the sibling search_guidance_sources by emphasizing that it lists the source set rather than searching it, but never names that sibling outright.

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 trigger ("Use when an agent first needs to see which... classes G05 can verify") and two explicit exclusions (not legal advice, not for unrelated GOV.UK content). It stops short of naming the follow-on alternative (search_guidance_sources) by name, so the routing is implied rather than spelled out.

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?

The description frames the tool as a passive read ("Return ... free state"), while annotations declare readOnlyHint=false, meaning the tool is not considered side-effect-free. That mismatch leaves the agent unable to know whether calling it changes anything. With annotations present the bar is lower, but a description that runs counter to them is a contradiction, not merely a gap.

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?

It is short and front-loads the verb, but the second "sentence" is a dangling one-word fragment ("Free.") that reads as an editing artifact rather than information. Minimal length is achieved partly by under-specification rather than by precision.

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?

An output schema exists, so return values need no prose, and with zero parameters the surface is small. Still, the undefined "free state" terminology and the ambiguity about whether the call has side effects leave the agent guessing at the tool's actual contract.

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?

The schema has zero parameters at 100% description coverage, so there is nothing for the description to clarify; the baseline for a parameterless tool is 4.

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 names a verb ("Return") and a resource (Public Discovery free state and intended introductory paid pricing), so an agent can roughly infer this is a pricing-readout tool distinct from the capability/guidance siblings. However, "Public Discovery free state" is jargon that is never defined, and the trailing fragment "Free." adds no clarity about what is actually returned.

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 indication of when to call this tool, no prerequisites, and no mention of how it relates to any of the nine sibling tools. The agent is left to infer usage entirely from the name.

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?

The description adds two traits beyond the annotations: it is a dry-run that does not return the substantive result, and it costs nothing ('Free') - neither is derivable from the structured fields. It does not, however, explain the surprising readOnlyHint=false, i.e. what side effect a 'check' has, nor what 'readiness' means operationally.

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?

It is short and front-loads the purpose, with no filler. But it is two terse fragments, the trailing 'Free.' lacks structural context, and the brevity is closer to under-specification than to disciplined conciseness.

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?

An output schema exists, so return values need not be described. Still, for a tool whose readOnlyHint is false and whose only parameter is undocumented, the description omits the side-effect profile and the meaning/source of capability_id - both needed for correct invocation, especially with a sibling list that already offers get_capability and list_capabilities.

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 single required capability_id is never mentioned in the description, so the agent gets no guidance on what identifier form is expected or that list_capabilities/get_capability supply it. One well-named parameter keeps this above the floor, but the description does not compensate for the coverage gap.

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 verb 'Check' and resource 'capability readiness' are identifiable, and 'preflight_request' does read as a distinct tool from siblings like get_capability and list_capabilities. However, 'bounded capability readiness' is undefined jargon that leaves the actual resource ambiguous, and there is no explicit differentiation from the sibling set.

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 when-to-use guidance, no stated alternatives, and no prerequisites. 'Free' implies a preflight-before-the-real-request pattern, which is weak implied usage context, but the description never says when to reach for this versus get_capability or aios_status.

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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, yet the description presents the tool purely as a lookup and never mentions whatever non-read-only behavior the hint signals. It does add one behavior not in the annotations ('Free'), giving cost transparency, and its 'bounded GOV.UK source set' wording is consistent with openWorldHint=false. Net: useful cost disclosure, but silent on the side-effect profile an agent needs.

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?

Two compact sentences with the usage trigger front-loaded, and the terse 'Free.' earns its place by disclosing cost. Nothing is padded. The density of unresolved jargon ('G05', 'monitored source') costs it the top mark.

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?

An output schema exists, so return values need not be described, and the single-parameter surface keeps the burden low. The description covers trigger, scope and cost. What is missing is differentiation from list_guidance_sources/get_guidance_changes and any hint about the non-read-only behavior flagged by annotations.

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% for the single 'query' parameter, so the description must carry the semantic load. It partially does so by implying the query is plain employment/payroll language to be mapped rather than exact codes, which is real information about input form. It gives no syntax, format, or example, so it does not fully compensate for the coverage gap.

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 second sentence gives a concrete verb+resource+scope: 'Searches only the bounded GOV.UK source set', which tells an agent this queries guidance content rather than enumerating it. The framing sentence adds that the function is mapping everyday employment/payroll wording onto a monitored 'G05' source. It stops short of explicitly distinguishing itself from the sibling list_guidance_sources, and 'G05' is never unpacked, so it is clear but not fully self-differentiating.

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 opening clause states a specific trigger ('Use when ordinary employment/payroll language must be mapped to a monitored G05 source before checking current official guidance'), including a sequencing instruction that this precedes consulting official guidance. That is strong when-to-use guidance. It names no alternative tool and gives no when-not condition, so it does not reach a 5.

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