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

With no annotations, the description carries the full disclosure burdenholistically, and it does add valuable behavior: 'omadacId is filled in automatically', the path/query/body routing convention, and the recommendation to consult get_operation_schema beforehand. What is missing is the risk profile: as a generic dispatcher this tool can execute mutating or destructive operations, and the description never warns about side effects or what happens with an unknown operation_id or malformed parameters.

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?

Three sentences, each earning its place: purpose first, followed by the mechanical routing rules, then the safety valve ('Use get_operation_schema first'). Dense and front-loaded with zero filler or repetition of schema structure.

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 description covers everything needed to invoke the tool: the key input, where each parameter class goes, the auto-filled omadacId, and the prerequisite lookup step. The gaps are the absence of an output schema and no disclosure of response variability or side-effect risk, which is significant for a no-annotation tool that can dispatch arbitrary operations.

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 0%, and the description fully compensates. It defines operation_id as the catalog key, gives concrete examples for path_params ('siteId, apMac'), distinguishes query_params from path_params, and scopes body to 'POST/PUT operations that take one'. The agent can route all four parameters correctly without any help from the schema's bare additionalProperties objects.

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: 'Call any cataloged Omada API operation by its operation_id.' The scope ('any cataloged... operation') immediately differentiates it from siblings: get_operation_schema retrieves schemas, search_operations finds operations, and list_sites/list_devices are specific catalog entries. An agent can tell this is the generic execution/dispatch tool without opening any schema.

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?

Provides strong routing guidance ('path parameters... go in path_params; query-string parameters in query_params; a JSON request body... in body') and explicitly names the prerequisite alternative: 'Use get_operation_schema first if unsure what an operation needs.' However, it never states when-not to use call_operation, and it omits search_operations as the step for discovering an operation_id in the first place.

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?

No annotations are provided, so the description carries the behavioral transparency burden. It discloses the returned content (method, path, parameters, request body schema) and implies a read-only operation by using 'Get,' but it does not address error behavior, prerequisites, or any side effects. This is acceptable for a simple schema lookup but leaves some behavioral detail implicit.

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 filler. It efficiently states the action and the retrieved elements, earning its place without 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?

The tool has a single parameter, an output schema, and a clear read-only purpose, so the description covers the essential operation. The presence of an output schema means return values need not be explained. Minor gaps remain—such as how to obtain operation_id—but the simplicity of the tool makes the description largely 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?

Schema description coverage is 0%, and the description only refers to 'one operation' without explicitly explaining what operation_id is or where it comes from. It does not mention formats, source via search_operations, or how to find a valid operation ID. Given the low schema coverage, the description fails to fully compensate for the missing 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 uses a specific verb ('Get') with a clear resource ('one operation') and enumerates the exact output scope: method, path, parameters, and request body schema. This distinguishes it from siblings like search_operations (searching) and call_operation (executing), leaving no ambiguity about what the tool does.

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 the use case—retrieve a single operation's schema—but does not explicitly state when to choose this tool over alternatives like search_operations or call_operation. No exclusions or alternative routing are provided, so an agent must infer usage from the verb and resource.

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?

With no annotations, the description carries the full burden. It clearly conveys a read-only listing action and global scope, but it does not disclose output format, pagination, authorization requirements, or behavior when no devices exist. These gaps are notable but not critical for such a simple read-only tool.

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 sentence with no filler. It front-loads the action and resource, then adds scope and examples of device types efficiently. Every phrase 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?

For a zero-parameter read-only list, the description adequately covers what is listed and the scope. The main gap is the absence of an output schema or return-format details, but the tool is simple enough that an agent can call it correctly without additional information.

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. The description adds meaningful context by stating 'across every site,' signaling that the tool is intentionally unfiltered and global, which is consistent with the empty input schema.

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 ('all managed devices'), and enumerates the device types included (access points, switches, gateways). It also establishes scope with 'across every site,' which distinguishes it from site-level tools like list_sites.

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 the tool should be used when an agent needs a global list of managed devices, and the phrase 'across every site' clarifies scope. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions.

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?

No annotations are provided, so the description carries the full burden. It mentions only that the tool lists sites and adds a scope, but it does not disclose whether this is a read-only operation, how pagination behaves, or what the response looks like. The presence of page/page_size parameters is ignored.

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, efficient sentence with no filler. It is appropriately short for a simple list operation, though it is so minimal that it leaves important behavioral and parameter context unaddressed.

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, no annotations, and no parameter descriptions, the description is incomplete for someone needing to invoke the tool correctly. The agent can infer basic behavior, but pagination details, return shape, and alternative selection are missing.

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 0%, so the description must compensate, but it does not explain page or page_size. The parameter names and defaults suggest standard pagination, but there is no clarification of limits, indexing, or how these values affect results.

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 ('List'), a resource ('sites'), and a scope ('this controller manages'). It is clear and distinguishable from siblings like call_operation or search_operations, though it does not explicitly differentiate from the similarly named list_devices.

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 guidance is given about when to use this tool versus alternatives. The sibling list_devices exists, but the description does not explain when to choose list_sites over list_devices or any other operation.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool re-fetches and rebuilds (implying mutation) and notes that it avoids a server restart. However, it does not mention potential side effects (e.g., temporary catalog unavailability, destructive behavior, or permission requirements). The disclosure is partial and leaves the agent uncertain about the operational impact.

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 core action stated first and the usage context second. It is front-loaded with the purpose and then a specific trigger, with no filler or redundant information. 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?

The tool has no parameters, an output schema exists (so return values need not be explained), and the description covers the purpose and when to use it. The added note about not restarting the server provides relevant operational context. For a simple refresh operation, the description is complete and sufficient 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, and schema coverage is trivially 100% since the input schema is empty. With no parameters to describe, the description's role is limited to the tool's action and usage, which it covers adequately. The baseline for 0 params is 4, and the description adds context about the refresh trigger, so this score 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 specific verbs ('re-fetch', 'rebuild') and names the exact resources (OpenAPI spec, operation catalog), making the tool's function unmistakable. It also differentiates itself from siblings like 'get_operation_schema' or 'search_operations' by focusing on the catalog refresh rather than querying or invoking 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?

Provides explicit when-to-use guidance: 'after a controller firmware upgrade'. This is a clear trigger condition that helps the agent decide when to invoke this tool instead of others. It also states the benefit ('pick up new/changed/removed endpoints without restarting this server'), which aids in decision-making.

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?

With no annotations, the description carries the burden of disclosing behavior; it does state matching scope, returned fields, and a follow-up recommendation. However, it does not disclose matching semantics (substring vs token), limit behavior, or whether the search is purely read-only, leaving some behavioral ambiguity.

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: one for purpose, one for matching/return details and follow-up. Every sentence adds information without redundancy, and the most important verb-resource pairing is front-loaded.

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 search tool with an output schema, the description covers purpose, match fields, return values, and a next-step hint. The only substantial missing context is the behavior/meaning of `limit` and potentially how many matches are returned by default, but the schema's default value partially mitigates this.

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 has 0% description coverage, but the description compensates for `query` by explaining what it matches against with concrete examples ('client', 'reboot'). It never explains `limit`, relying on its name and default value, so parameter clarification is only partially 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 opens with a specific verb and resource ('Search this controller's Omada API operations by keyword') and enumerates exactly what fields are matched and returned. This makes the tool's purpose unmistakable and distinguishes it from siblings like call_operation or get_operation_schema.

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?

It clearly implies the intended use — finding operations by keyword before invoking them — and explicitly advises calling get_operation_schema when parameters are unclear. It lacks an explicit when-not-to-use or comparison with sibling search alternatives, so it stops short of full routing 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?

No annotations are provided, so the description carries the full behavioral burden. The verb 'Report' implies a read-only, side-effect-free query, which is adequate transparency for a zero-parameter info tool. However, it does not explicitly state that it is safe to call anytime or that it reflects current server state.

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 clean sentence that front-loads the verb and the object of the query. Every word contributes; there is no filler, redundancy, or irrelevant 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?

For a zero-parameter query tool with an output schema present, this description is complete. The purpose is fully stated, the return value details are covered by the output schema, and there are no parameters or prerequisites to explain.

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 the input schema confirms an empty object with additionalProperties=false. With 0 params, the baseline is 4; the description correctly adds no param information because there is nothing to document.

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 identifies a specific verb ('Report') and a specific resource ('which Omada API spec this server is running against'). It is distinct from all siblings, which deal with operations, catalog, sites, and devices — this one is clearly a server-level metadata query, so an agent can differentiate it without inspecting schemas.

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 explicit guidance on when to use this tool versus alternatives, nor any exclusions. However, usage is implied: an agent needing to know the server's API spec version would naturally call this, and none of the siblings overlap with it. The context is clear but the description does not spell out when-not-to-use.

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