Alkemata Public Knowledge

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description reinforces the read-only nature ('read-only operating rules') but adds no new behavioral context such as freshness, caching, or scope of the references.

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 or redundancy. Every word contributes to the purpose statement.

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 parameters, full annotation coverage, and an output schema to describe return values, the description carries little remaining burden. It is complete enough, though a note on what the guidance covers or when to consult it would fully close the loop.

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; the baseline of 4 applies. No parameter syntax or semantics are 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 ('Returns') and a clear resource ('authoritative public references and read-only operating rules for agents'), which is distinct from the content/search siblings. It stops short of explicitly naming how it differs from alkemata-get-site-info or the content tools, so it is clear but not sibling-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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling tool is named as an alternative. The phrase 'for agents' only weakly implies the intended caller, leaving the agent to infer the triggering context.

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=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral constraint beyond that: only 'published' content is returned, implying drafts or private items are not accessible. It says nothing about what happens on a missing or unpublished ID, but with annotations carrying the main burden a 3 is fair.

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 well-formed sentence that front-loads the verb and resource and ends with the lookup key. No filler, no redundancy.

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 one-parameter read tool with an output schema, full schema coverage, and complete safety annotations, the description supplies everything an agent needs to invoke it correctly. The only remaining gap is the absence of routing guidance toward or away from the search sibling, which is minor given how simple the tool is.

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%: the single post_id parameter is typed as integer, bounded at minimum 1, and described as a 'Numeric WordPress post or page ID.' The description's 'by numeric ID' adds no detail beyond the schema, so the baseline 3 for full schema coverage 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?

The description states a specific verb ('Returns'), a specific resource ('one published Alkemata post or page'), and the lookup key ('by numeric ID'), so an agent can immediately tell what it fetches. It does not explicitly name the sibling alkemata-search-published-content as the alternative, but the singular 'one ... by numeric ID' framing implicitly contrasts with a search tool.

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 guidance on when to use this tool versus alkemata-search-published-content, nor any stated prerequisites (e.g., that the ID must come from a prior search). Usage must be inferred entirely from the singular-vs-search framing.

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=false, so the safety and determinism profile is fully covered by structured data. The description adds only the qualifier that the returned identity/URLs are public, which is modest context rather than a new behavioral trait.

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 or repetition. It is appropriately sized for a zero-argument read tool, though it is terse to the point of omitting any routing or usage 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, the description is not obligated to enumerate return fields, and with no parameters there are no argument semantics to document. The only gap is the absence of sibling-routing context, which keeps it short of a 5 for a tool that sits among three other read-oriented siblings.

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 input schema defines zero parameters, so there is nothing for the description to clarify. The baseline for a parameterless tool applies, and no misleading parameter claims are 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?

States a specific verb (Returns) and resource (public identity and interface URLs for Alkemata), which is concrete enough for an agent to know what data it yields. It does not, however, distinguish itself from siblings such as alkemata-get-agent-guidance or alkemata-get-published-content, leaving the agent to infer the boundary from the resource noun alone.

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 discovery/bootstrap use case (obtaining site identity and interface URLs) but never states when to call it, when not to, or how it relates to sibling tools. Usage is only inferable from the returned-content phrasing, which is the definition of implied guidance.

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, openWorldHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context that only public metadata is returned, which is behavior beyond the annotations. It does not discuss authentication or rate limits, but those gaps are minor given the annotation coverage.

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 with no wasted words. It communicates the core action and output scope immediately. Every sentence earns its place.

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 the description need not explain return values. The schema fully documents parameters and annotations cover the safety profile. The description adds the public-metadata scope but omits guidance on sibling tool selection, leaving a small 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 description coverage is 100%, so all three parameters are already documented in the schema. The description adds no parameter syntax or format details beyond what the schema provides. The baseline score of 3 is appropriate when the schema carries the parameter 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 states a specific verb and resource: 'Searches published Alkemata posts or pages.' It also scopes the result to 'public metadata only.' However, it does not explicitly differentiate itself from sibling tools such as alkemata-get-published-content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit when-to-use guidance or alternatives. It does not explain when to search rather than use alkemata-get-published-content or alkemata-get-site-info. The agent must infer usage solely from the tool name and description.

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