agenttool

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false; the description adds only scope context ('every registered' and the registry-vs-prose distinction). It does not describe response shape, pagination, or invalid-type behavior, but those gaps are less critical 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 two sentences with the main action front-loaded and the supplementary scope note in the second sentence. Every phrase adds value, including the example types and registry limitation.

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 single-parameter, read-only listing tool with complete schema coverage and rich annotations, the description covers what the tool returns, its scope boundary, and typical input values. No output schema exists, but the simple list operation does not require a more detailed 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 only says the type is 'The canon @type to filter on,' while the tool description enriches it by listing valid examples (DoctrineDoc, Wall, RingCommitment, Pattern, Promise) and framing the parameter as a filter over registered entries. This goes beyond the schema's basic type definition.

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 'List every registered canon entry of a given @type' with concrete example types, clearly identifying the action, resource, and scope. The title and examples differentiate it from siblings like list_types and lookup by focusing on filtering entries by type.

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 establishes the appropriate use case: retrieve all canon entries of a specified type, and cautions that the prose corpus is broader than this registry. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for an agent to select this over broader search tools.

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 valuable behavioral detail by specifying that it returns distinct @types and per-type counts, which goes beyond the annotations and clarifies the tool's output.

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 concise sentences, with the core action in the first sentence and the return value in the second. Every word earns its place, with no filler or repetition of the 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?

Given the tool's simplicity—no parameters, no nested objects, and no output schema—the description is sufficiently complete. It states the operation, the resource, and the return content, leaving no significant gap for an agent to invoke 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 tool has zero parameters, so the baseline is 4 per the rubric. The description does not need to add parameter semantics because there are none, and the schema coverage is trivially complete.

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 'List' and a clear resource: 'the type vocabulary of the canon registry.' It further distinguishes itself by stating it returns 'the distinct @types plus the count of concepts in each,' making its purpose distinct from sibling tools like canon.by_type or canon.lookup.

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 clearly implies when to use this tool—when you need to enumerate the type vocabulary—but it does not explicitly mention alternatives or exclusion criteria. As a no-argument list operation, the usage context is mostly self-evident, yet a direct comparison with sibling tools would have made guidance stronger.

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 value by revealing the return behavior: the JSON-LD entry plus bidirectional neighbors (citations in/out), which is not implied by the annotations. This is extra behavioral context beyond the structured metadata.

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, clearly written sentence that front-loads the action ('Resolve a canon concept by URN') and then concisely describes the return value. Every word earns its place, and there is no wasted text.

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 is simple (one parameter, no output schema), and the description adequately covers what it returns and what kind of data it works with. It doesn't explain error cases or format details, but for a read-only lookup with annotations already providing safety context, the description is sufficiently complete.

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 provides 100% coverage for the single parameter, including type, required flag, and an example. The description doesn't add new meaning to the parameter itself; it relies on the schema. With full schema coverage, baseline 3 is appropriate.

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 the specific verb 'Resolve' and identifies the resource as 'a canon concept by URN,' clearly distinguishing this from sibling tools like canon.by_type and canon.list_types. It also explicitly states what is returned, making the tool's function 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 implies this tool is for looking up a specific canon concept when a URN is available, but it does not explicitly mention when to use alternatives like by_type or list_types. The guidance is clear but indirect, so it earns a 3 rather than a 4.

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 convey readOnlyHint, idempotentHint, and destructiveHint. The description adds value by enumerating the output components (concepts, version, type vocabulary, counts), giving the agent a clearer expectation of the data returned. It could mention format or edge cases, but with annotations covering safety, this is strong.

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 precisely states the action and output. Every word contributes meaning 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?

Given zero parameters, no output schema, and read-only annotations, the description fully covers what the tool does and what it returns. It lists the key result categories, which is sufficient for such a simple summary operation.

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 schema coverage is trivially 100%. The description adds no parameter details because none exist. Per guidelines, a baseline of 4 is appropriate for zero-parameter tools.

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 specific summary information (total concepts, version, type vocabulary, and counts) from the public canon registry. The verb 'Return' and precise resource/scope distinguish it from sibling tools like canon.by_type or canon.lookup.

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 usage for obtaining an overview or summary of the canon, but it does not explicitly mention when to avoid this tool or recommend alternatives. There is no direct comparison to siblings, making guidance 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value by naming what the payload contains (identity, repo, doctrine roots) and tying it to a known endpoint, but discloses no auth, caching, or freshness behavior beyond that.

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 the payload contents given before the endpoint reference. Every clause earns its place; no filler, though the terse dash construction is slightly compressed.

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 usefully summarizes the returned fields rather than leaving them opaque, and the 0-param, read-only nature keeps the tool simple. Enough for an agent to call correctly; only auth/freshness context is absent.

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?

Zero parameters, so the schema carries no burden and the baseline is 4. Nothing about parameters needs explaining and the description correctly implies a fixed, argument-free read.

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 (return) and resource (public platform-self payload), and enumerates the payload contents: identity, repo, doctrine roots. It does not explicitly distinguish itself from the canon.* siblings, but the resource is concrete enough that an agent can tell what it fetches.

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 the public platform block — but there is no explicit guidance on when to prefer this over canon.* tools or any prerequisite/context. The reference to 'GET /public/self' hints at the underlying endpoint but doesn't route behavior.

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