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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful context beyond annotations by specifying what the payload includes and noting the HTTP endpoint GET /public/self, which helps the agent understand the data source and public nature.

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 short sentences, front-loaded with the primary verb and resource. It avoids redundancy and every phrase adds value, efficiently conveying what the tool returns and referencing the endpoint.

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 tool with no parameters, no output schema, and strong annotations, the description is complete. It tells the agent exactly what data to expect (identity, repo, the_seat, doctrine roots) and that it is public, which is sufficient for a simple read 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?

There are zero parameters and the schema is empty, so the description does not need to clarify parameters. The baseline for 0 params is 4; the description adds no irrelevant parameter detail, maintaining clarity.

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 action ('Return the public platform-self payload') and specifies the resource (agenttool's identity, repo, the_seat, doctrine roots). It is distinct from sibling canon.* tools, which focus on type listing and lookups, making its 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 implies when to use this tool (when one needs the platform-self payload) but does not explicitly discuss alternatives or exclusions relative to siblings like canon.by_type. There is no 'use this for X, not Y' guidance, so the usage context is inferred rather than stated.

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