Praetorium

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real behavioral value by characterizing the payload as a "complete bounded document" with source location, revisions and attribution — telling the agent this is the full record rather than a snippet, and that the response is size-limited.

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?

A single front-loaded sentence that identifies the source of the id and the contents of the return in minimal words. Nothing is redundant or padded.

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 shape need not be re-explained, and the description covers the input provenance. What is missing is disambiguation from get_reference_record — with a sibling that close, the definition should say how the two differ to prevent misselection.

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 single parameter's description ("The stable result id returned by search_reference") is essentially duplicated in the tool description. With the schema doing the heavy lifting and only one parameter, this is the baseline 3 — no added syntax, format or constraint 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+resource ("Reads the complete bounded document") and ties it to the search_reference output via the result id, which clearly separates it from the search/list siblings. It does not, however, distinguish itself from the very similar sibling get_reference_record, leaving that ambiguity for the agent to resolve.

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?

"returned by search_reference" implies the prerequisite workflow (search first, then fetch by id), which is useful usage context. But there is no explicit when-to-use/when-not guidance and no mention of the near-identical get_reference_record alternative, so tool selection is left partly 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, and closed-world behavior, so the safety profile is fully covered. The description adds only which record types exist (mission cards, deployments, terrain, detachments, datasheets) and nothing about failure modes for an unknown id or the response shape.

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?

A single front-loaded sentence with no filler, carrying the tool's purpose and its data-domain breadth. Slight jargon ('source-faithful') costs a point but nothing is wasted.

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 rich annotations, a 100%-documented one-param schema, and an output schema that carries return values, little is left for the description to do, and it covers what the record contains. The unresolved overlap with get_reference is the main 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% with a single required id parameter whose description already states it comes from search_reference or list_reference. The description adds no additional parameter meaning, so the baseline of 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 (Returns) and resource (source-faithful structured record) and scopes it to records behind a search result. It does not explicitly contrast with the close sibling get_reference, so an agent must infer the distinction rather than being told.

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?

Phrases like 'behind a search result' imply it should be called after search_reference, and the id parameter description ties it to search_reference/list_reference. But there is no explicit when-to-use rule or exclusion versus get_reference or list_reference.

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 fully covered. The description adds only the idea that these values are filter inputs, and says nothing about ordering, completeness of the list, or caching behavior.

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?

A single front-loaded sentence with no filler; every word earns its place for a trivial enumerator.

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 parameters and an output schema exists, so return values need not be explained. Combined with the annotations, the description is sufficient, though a note connecting these factions to the narrow-search parameter would close the 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline of 4 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 (Lists) and resource (factions in the Praetorium reference), so the agent knows exactly what is returned. It does not explicitly contrast with siblings like list_units or list_reference, but the scope is unambiguous.

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 clause 'that can be used to narrow reference searches' implies the downstream use case, telling the agent this feeds search_reference filtering. However, it gives no explicit when-to-use/when-not guidance or names an alternative tool.

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 fully covered and the description need not restate it. The description adds a small amount of behavioral nuance by scoping results to 'active source revisions', but says nothing about scope limits, pagination, or what is excluded from the catalogue.

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?

A single front-loaded sentence that names the discovery verb first and then the resources returned. There is no filler, redundancy, or trailing boilerplate to trim.

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, the description is not obliged to explain return values, and the enumerated resource kinds give the agent enough to know what it will receive. The only real gap is the absence of sibling routing guidance, which is a usage concern rather than a completeness one.

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 per the rubric the baseline is 4. No additional parameter meaning is needed or expected, and the description correctly avoids inventing filter options that the schema does not expose.

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 'Discovers' plus the enumerated resource set (factions, mission packs, rule documents, reference kinds, active source revisions) makes clear this is a catalogue-enumeration tool rooted in the 'Praetorium reference' domain. It does not, however, differentiate itself from siblings like list_factions, list_units, or search_reference, which sound like overlapping listing operations.

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 only implied: 'Discovers available...' suggests this is the browsable entry point for the catalogue, but there is no explicit when-to-use statement, no mention of prerequisites, and no routing guidance versus get_reference, get_reference_record, or search_reference. The agent must infer this is a discovery-first call.

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 and non-destructive, so the safety profile is covered. The description adds that the response is 'one bounded response', which hints the agent need not paginate, but most of the text enumerates return contents that the existing output schema already supplies.

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, front-loaded with the primary action ('Returns every pickable unit'), and each sentence earns its place by covering scope then the detachment option. The field enumeration is dense but not wasteful.

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 not be explained, and the description adequately conveys scope plus the detachment behavior. It is only thin on when to prefer this over sibling listing tools.

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%, so the schema already documents all three parameters, giving a baseline of 3. The description adds real meaning for detachment (including it yields complete rules, enhancements and stratagems), but says nothing about faction or battleSize beyond what the schema states.

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: returns every pickable unit for a faction, and enumerates the returned fields (costs, composition, attachments, limits, roles, keywords). It does not explicitly contrast with siblings like list_factions or get_reference, so the agent must infer the boundary, but the resource is specific enough to distinguish it.

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 second sentence implies a usage path: add a detachment to get its full rules and enhancements in one call rather than opening pages individually. However there is no explicit when-to-use vs alternatives (list_factions, get_reference) and no stated prerequisites beyond the schema's required faction.

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/openWorld=false/idempotent/non-destructive, so the safety profile is covered. The description adds that results are 'verified' text with bounded excerpts, canonical URLs, revisions, and attribution, which is useful context about result character, though return shape is also covered by the output schema.

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 tight sentences, zero filler, and the core purpose is front-loaded before the return-value note.

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?

Output schema exists, so return values need no prose. However, a 7-parameter search tool with 14% schema coverage leaves filtering and pagination semantics undocumented, which is a meaningful gap 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 only 14% (just the query field), and the description only implicitly gestures at the 'kinds' dimension via the content list. pack, faction, document, cursor, and limit go unexplained in both places, so 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 (searches) and resource (the reference text used by Praetorium), and enumerates the content domains (mission, rules, detachment, datasheet). It reads as the search entry point against the get_/list_ siblings, though it never names them 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 guidance and no routing against the siblings (get_reference, list_reference, get_reference_record). The agent must infer that this is the keyword-search tool rather than a list or fetch tool.

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