Plato's Kallipolis

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

The annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context by explicitly stating that compilation does not execute retrieval and does not contact providers, which materially affects how an agent would invoke or interpret this tool beyond the annotations.

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 two tight sentences. The primary action and output scope are front-loaded, and the clarifying non-execution guarantee is placed immediately after. Every sentence earns its place with no redundancy or 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?

The tool has seven parameters, nested objects, and an output schema. Annotations and output schema cover safety and return structure, but the description leaves parameter semantics and when-to-use guidance under-specified. It is minimally viable but not fully complete 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?

With 0% schema description coverage, the description needed to compensate by explaining parameters such as intent, limits, sources, policy, or output. It does not. It only mentions plan dimensions, which helps understand the high-level output but leaves parameter semantics largely to inference from property names.

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 uses a specific verb ('Normalize'), names the resource ('a public-data query'), and enumerates the plan dimensions produced (evidence, freshness, latency, result, cost). The added statement that compilation does not execute retrieval or contact providers distinguishes it clearly from the sibling data-returning tools.

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 implies this is a planning-stage tool for public-data queries, and the non-execution statement suggests it should be used when retrieval is not yet wanted. However, it never explicitly says when to prefer this over alternatives or provides exclusions, so the guidance remains indirect.

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, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful context about metric categories and privacy/interpretation boundaries, but it remains vague about what those boundaries entail and does not detail any behavioral quirks beyond the annotations.

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 front-loaded sentence that immediately states the action and resource, then lists the returned categories and boundaries. There is no filler or redundancy, and every phrase adds 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?

For a zero-parameter, read-only tool with an output schema and strong annotations, the description covers the core behavior and return categories adequately. It is arguably complete enough for invocation, though terms like 'contract-only' and 'interpretation boundaries' are not expanded, and no usage context is given.

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 has zero parameters and 100% schema description coverage, so the baseline is 4. The description does not need to explain parameters, and it does not introduce any parameter-related ambiguity.

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 clearly states the tool returns growth metrics categorized as enabled, partial, contract-only, and unavailable, and mentions privacy and interpretation boundaries. It is specific and generally clear, but it does not explicitly differentiate from sibling tools such as get_niulai_info, so it stops short of the highest score.

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 provides no guidance on when to use this tool versus alternatives like compile_query_plan, get_niulai_info, or search_agents. There are no exclusions, prerequisites, or decision rules, leaving the agent to infer usage from the tool name alone.

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 communicate read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond annotations by specifying that the returned data is publisher-declared and scoped to particular information categories, which clarifies the data's nature and boundaries.

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 front-loaded sentence that states the action first and then lists the content categories. It contains no filler, repetition, or extraneous detail.

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 the tool has no parameters, rich annotations, and an output schema, the description is complete for an agent to call it correctly. The output schema covers return structure, and the description covers the semantic scope.

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 has zero parameters, so the schema fully documents the parameter surface. The description compensates by making the fixed scope explicit, which is the only semantic information an agent needs.

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 uses a specific verb ('Return') and names a particular resource (NIULAI community asset information), then enumerates the covered domains: Base network, contract, claim, community-role, custody, and risk-boundary. This level of specificity clearly separates it from siblings such as get_growth_metrics and search_agents.

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 implies when to use the tool: whenever an agent needs publisher-declared NIULAI asset information. It does not explicitly state when not to use it or name alternative tools, so the guidance is implied 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?

The annotations already provide readOnlyHint, idempotentHint, and non-destructive behavior. The description does not contradict these and adds no unnecessary side-effect claims. The simple retrieval behavior is accurately represented.

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, clear sentence with no redundancy. It efficiently conveys the action, the resource type, and the key identifying attribute.

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 the simple single-parameter input and no output schema, the description sufficiently conveys what the tool returns (a complete prepared resource profile with evidence-backed facts and provenance). No additional context is needed for an agent to use 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?

The sole parameter 'resourceId' is described as a 'stable resource ID' in the tool description, which aligns with the parameter name and the string pattern in the schema. This provides sufficient meaning for the parameter without needing additional schema-level documentation.

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 clearly states the tool retrieves one complete prepared resource profile by its stable resource ID, distinguishing it from search_resources which likely searches for resources. The verb 'Retrieve' and the specific object 'complete prepared resource profile' make the purpose 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 description implicitly provides usage guidance by specifying 'by its stable resource ID', indicating that this tool is appropriate when an ID is known, while search_resources would be used for discovery. This differentiates it from sibling tools without explicit alternatives.

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 annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context with 'public agent registry' and especially 'Preview data only', indicating that results are partial rather than comprehensive records. This is useful behavioral information beyond the annotations.

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 front-loaded sentence plus a short clarifying sentence. Every word earns its place, and there is no redundancy or 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 simple two-parameter tool with an output schema, required-param count of zero, and supportive annotations, the description is complete. It communicates scope, safety, and the preview nature of the results without needing extensive elaboration.

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 already documents 'capability' with a useful description and 'protocol' with a self-explanatory enum and default. The description confirms both parameters ('by capability and protocol') but adds no additional formatting or semantic detail beyond the schema. At 50% schema coverage, this is adequate but not compensatory.

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 uses a specific verb ('Search'), identifies the resource ('public agent registry'), and states the search dimensions ('by capability and protocol'). This clearly distinguishes it from the sibling tools, which concern query plans, growth metrics, and Niulai info.

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 provides clear context for when to use the tool: searching the public agent registry by capability and/or protocol. It does not explicitly name alternatives or exclusion conditions, but the sibling tools are clearly unrelated, so an agent can infer the appropriate use case.

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, and destructiveHint=false, so the safety profile is known. The description adds the offline nature ('without contacting external providers') and the fixed scope of 350 prepared profiles, which is useful context. It does not contradict annotations and provides additional behavioral context beyond the structured fields.

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, well-structured sentence that front-loads the action and scope, followed by the key distinguishing feature (offline search). Every word earns its place with no redundancy or fluff.

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 the presence of an output schema (not shown but indicated) and the detailed parameter descriptions in the schema for q, the description adequately covers the search scope, offline behavior, and criteria. It does not mention pagination (limit/cursor) but those are defined in the schema. For a read-only search tool, the description is sufficiently complete, though it could briefly mention when to use it vs alternatives.

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 25% (only q has a detailed description, which is already extensive). The tool description gives a high-level summary of search criteria (category, keyword, hostname) but does not explain limit or cursor parameters. Since q's description is already in the schema, the tool description adds little new meaning for that parameter, and it fails to compensate for the undocumented limit and cursor. However, the summary does map 'keyword' and 'hostname' to q, offering some guidance.

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 clearly states the verb 'Search', the resource '350 prepared structured resource profiles', and the search criteria (category, keyword, hostname). It also explicitly notes 'without contacting external providers', distinguishing it from potentially external search tools. This differentiates it from sibling tools like search_agents by specifying 'resource profiles'.

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 implies a use case for local, offline resource search but does not explicitly state when to use this tool versus alternatives. It does not mention search_agents or get_resource or provide exclusion conditions. The 'without contacting external providers' hint suggests a preference for offline search, but the guidance is not explicit.

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