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

With no annotations provided, the description carries the burden of disclosing behavior. It clearly states that the tool performs an authentication check and returns a version string, and it names the wrapped API. This is transparent for a simple read/check operation, though it does not describe failure behavior.

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?

Two sentences, no filler, with the core purpose front-loaded. Every phrase adds useful information: what it confirms, what it returns, and the wrapped API method.

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 connectivity check with no output schema, the description is complete: it states the action, the target system, the return value, and the underlying API. Nothing essential is 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?

The tool has zero parameters, so there is little to document. The description explicitly states 'No parameters required,' which reinforces the empty schema and removes any ambiguity for the agent.

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 ('confirms'), a specific resource ('server can authenticate to the configured S2 NetBox controller'), and a concrete outcome ('returns the NBAPI version string'). It also names the wrapped API method (GetAPIVersion), which clearly distinguishes it from the many get/list sibling 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 gives clear context for when to use the tool: to verify server authentication/connectivity to the S2 NetBox controller. It does not explicitly name alternatives or exclusions, but among siblings it is the only connection-checking tool, so the usage context is clear.

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 behavioral burden, and it does so thoroughly. It discloses case-insensitive matching, the all-terms-must-match rule, the fields searched, the full-page reads of GetPortals and GetReaders, the join key READERKEY, and the special case of portals with no reader description. This is far beyond what the minimal schema or annotations would provide.

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?

Every sentence is functional: the first states what it finds, the second clarifies name semantics and examples, the third defines exact matching behavior, and the fourth explains the no-reader-description edge case. There is no filler or repetition of the schema.

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 low complexity (one required parameter), no annotations, and no output schema, the description provides enough detail for an agent to invoke it correctly and understand matching behavior. It does not describe the output shape or error cases, but those are less critical for a search-style tool when the matching and result inclusion behavior are already clearly specified.

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?

Although the schema already describes the single query parameter with examples, the description adds substantial meaning beyond it: whitespace-separated terms are treated as separate search terms, matching is case-insensitive, and every term must appear for a match. These semantic rules materially affect how an agent should construct a query, so the description earns credit above the baseline.

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 'Finds' with a clearly defined resource, 'portals (doors)' and explains exactly what is searched: name, reader names, and reader descriptions. It effectively distinguishes this tool from sibling raw-listing tools like get_portals and get_readers by describing a joined, term-based search rather than a raw retrieval. The example site codes and human-readable names make the intent unmistakable.

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 main use case: searching for portals by location or name rather than listing all portals. However, it never explicitly says when to use this tool versus siblings like get_portals or get_readers, and it gives no exclusion criteria. The agent must infer the alternative from the sibling list and 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?

No annotations are present, so the description carries the burden. It discloses the default-off vs default-on asymmetry for RESOLVENAMES/RESOLVEDESCRIPTIONS, the cost model (per-person GetPerson calls, per-call GetReaders fetch), and the fact that identification is only by ENCODEDNUM/HOTSTAMP. This is exactly the kind of non-obvious behavior an agent needs.

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 first sentence is efficient, but the long second half repeats the schema descriptions for RESOLVENAMES and RESOLVEDESCRIPTIONS almost verbatim. Useful rationale remains, but the description could be trimmed to distinguish only what the schema doesn't say.

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 no output schema, it explains the record shape (grant/deny, enriched fields) and all non-obvious defaults. It doesn't list every possible returned field or describe errors, but for an optional-filter lookup with a fully described schema, the essential context is present.

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 covers all 9 parameters at 100%, including default values and cost notes. The prose adds a few contextual clues (PERSONID absence, codebase-wide inverted default, rationale for opt-in), but much of it duplicates the schema, so it hovers just above the baseline.

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: 'Returns historical access (grant/deny) records' and immediately clarifies the identifying keys (ENCODEDNUM/HOTSTAMP, not PERSONID), which separates it from person-oriented history tools. It could have explicitly named a sibling like get_reader_access_history, so it is not a 5.

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 describes what filters exist and how to toggle enrichment, so a caller knows the operational knobs, but it never states when to prefer this tool over get_reader_access_history or get_event_history. The usage is implied by 'historical access (grant/deny) records' rather than explicitly contrasted.

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 behavioral burden and does so thoroughly. It discloses the inverted default, two full-table fetches per call, fixed cost, the fact that THREATLEVELGROUPKEY is never resolved, and the exact effect of setting RESOLVEGROUPNAMES to false.

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 long but dense and front-loaded with the core purpose. Some content repeats the schema's parameter descriptions, but the added behavioral and performance context makes the length justifiable.

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 no output schema and no annotations, the description is remarkably complete. It explains the return behavior for both default and opt-out paths, the resolution semantics, the unresolved key, and the performance cost, leaving no ambiguity about how the tool behaves.

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?

Input schema coverage is 100%, so the schema already documents both parameters in detail. The description adds value beyond the schema by noting the raw response contains only bare foreign keys, that the resolution cost is fixed because each access level has exactly one of each key, and that it wraps NBAPI GetAccessLevel.

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: 'Returns the details of a single access level for a given ACCESSLEVELKEY.' This clearly distinguishes it from plural/list siblings like get_access_levels and from group-focused tools like get_access_level_group.

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 establishes the tool's scope—single access level lookup by key—so an agent can infer when to use it. It does not explicitly name alternative tools or state when not to use it, but the singular/plural contrast and key requirement provide clear contextual 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?

With no annotations, the description must carry the behavioral burden. 'Returns' and 'wraps NBAPI GetAccessLevelGroup' indicate a read operation and external API coupling, but there is no explicit statement about side effects, errors, permissions, or rate limits. Adequate for a simple read, but not comprehensive.

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?

One sentence with no wasted words: function first, then key, then underlying API wrapper in a parenthetical. It is well-structured and easy to scan.

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-key lookup, the description and schema cover the basics. However, with no output schema and no annotation, the agent still doesn't know what 'details' includes or what happens for missing/invalid keys, leaving some uncertainty.

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 coverage is 100%, and the schema already documents ACCESSLEVELGROUPKEY as the required unique key. The description only restates that the tool retrieves the group for that key, adding no extra format, constraints, or usage details beyond the 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?

States a specific action ('Returns the details') on a specific resource ('a single access level group') keyed by ACCESSLEVELGROUPKEY. The word 'single' helps differentiate it from plural siblings like get_access_level_groups, though it doesn't enumerate which details are returned.

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 retrieving one group when you have a specific key, but it never names alternatives such as get_access_level_groups or states when not to use it. Usage context is present only by implication.

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 of behavioral disclosure. It mentions wrapping NBAPI GetAccessLevelGroups but does not describe pagination behavior, response format, partitioning implications, or any operational expectations such as whether this is a read-only operation.

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 communicates the essential action and resource immediately, and the parenthetical NBAPI reference provides useful implementation context without bloat.

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 listing tool, the description is minimally adequate, but with no annotations and no output schema, it leaves gaps around pagination and how to continue listings using STARTFROMKEY. The schema documents the parameters, so this is not severely incomplete, but an agent would benefit from more invocation context.

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%, with both PARTITIONKEY and STARTFROMKEY already described in the input schema. The tool description adds no additional parameter-level meaning beyond the NBAPI wrapper reference, so the baseline score of 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 states a clear verb ('Lists') and a clear resource ('access level groups configured on the NetBox system'), and the plural 'groups' distinguishes it from the singular sibling get_access_level_group. It is specific enough, though it does not explicitly name or differentiate itself from related 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 gives no guidance on when to use this tool versus the singular get_access_level_group or get_access_levels. It only states what the tool does, so an agent must infer usage context from the name and siblings.

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 behavioral burden. 'Lists' and 'wraps NBAPI GetAccessLevelNames' convey a read-only enumeration and tie the tool to a known API, but the description does not disclose return shape, pagination behavior, or any constraints beyond what the schema already documents.

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, resource, and backend wrapper with no filler. It is appropriately sized for a simple list tool.

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 combination of the description and the fully documented schema is sufficient to invoke the tool, but the definition is thin for tool selection: it does not explain how the returned names relate to the sibling access-level tools or what the output looks like. Given no output schema and no annotations, a bit more context would make it 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 100%, and both optional parameters (PARTITIONKEY, STARTFROMNAME) have meaningful descriptions, so the description does not need to repeat them. The tool description adds no additional parameter-level context, so the schema baseline of 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 clearly identifies the operation ('Lists access level names') and the resource scope ('configured on the NetBox system'), and the wrapper reference adds endpoint precision. It does not explicitly differentiate itself from siblings like get_access_levels or get_access_level, though the word 'names' implies the distinction.

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 about when to call this tool versus get_access_levels, get_access_level, or get_access_level_group(s). The description only states what it does; it never provides conditions, exclusions, or alternative suggestions.

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 provided, the description carries the full burden. It states the tool 'lists' access levels, implying a read-only operation, but it does not describe pagination behavior (despite STARTFROMKEY/STARTFROMNAME parameters), response format, or any side effects or requirements. An agent cannot infer how the pagination cursors work or what the output looks like.

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 redundant phrasing. It is concise, though it sacrifices useful behavioral and usage context. For conciseness alone it earns a 4.

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?

There is no output schema, so the description must explain what the tool returns and how the pagination parameters work. It merely says 'lists access levels' without detailing the return structure or how to use STARTFROMKEY/STARTFROMNAME to iterate through pages. For a listing tool with multiple optional parameters, this is insufficient for an agent to call it correctly beyond trivial cases.

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 100% coverage, with each parameter carrying a description (e.g., 'Pagination cursor (key) to continue listing from a previous call'). The tool description itself adds no additional parameter meaning beyond what the schema provides, so it meets the baseline 3 for high schema coverage.

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 'Lists' and identifies the resource 'access levels configured on the NetBox system', clearly distinguishing it from sibling tools like get_access_level (singular) or get_access_level_name. The mention of wrapping NBAPI GetAccessLevels further anchors its function.

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 purpose implies this tool is for enumerating access levels, but it does not explicitly state when to use it versus alternatives such as get_access_level for a single record or get_access_level_names for just names. No exclusions or direct comparisons are provided.

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 provided, the description carries the full burden. It discloses the response format (ALARMS/ALARM collection) and the behavior for no active alarms (empty collection or NOT FOUND), which is valuable. However, it doesn't mention authentication, permissions, or potential side effects, though as a read-only get operation this is less critical. The disclosure is sufficient for a basic understanding.

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 concise, with two sentences that front-load the primary purpose and then add response behavior. No wasted words; every sentence contributes useful information.

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 6 optional parameters and no output schema. The description gives a high-level response type and handles the empty case, which is helpful. However, it doesn't describe the alarm object structure or any pagination, but for a read-only retrieval with optional filters, this is adequate. It's complete enough for an agent to understand what it returns and when to call it.

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 coverage is 100%, so each parameter already has a description. The tool description adds a natural-language summary of the filter options (partition, alarm ID, event ID, activity ID or owner), but does not provide additional semantics beyond the schema. It meets the baseline but adds little extra value.

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 alarm information from the NetBox system, with a specific set of optional filters (partition, alarm ID, event ID, activity ID or owner). It distinguishes itself from other get_* tools by naming 'alarm information' and the wrapped NBAPI GetAlarms, 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 does not explicitly state when to use this tool versus alternatives or when not to use it. While it's implied that this is the tool for retrieving alarms, there is no guidance on choosing it over related tools like get_event_history or list_events, nor 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?

With no annotations, the description carries the full burden. It discloses several non-obvious behaviors: the inverted default of RESOLVEDESCRIPTIONS (true instead of false), the performance cost of a GetReaders full-table fetch per call, and the single GetPerson lookup for RESOLVENAMES. It also explains where enriched fields land (top-level vs per-record). This is a highly transparent description.

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 dense but every sentence earns its place. It is front-loaded with the core purpose, then logically proceeds through identification, defaults, cost trade-offs, and response placement. Despite its length, there is no filler—every clause conveys essential information about behavior, defaults, or alternatives.

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 a complex tool with 6 parameters, no output schema, and no annotations, the description covers all critical aspects: purpose, identification method, parameter defaults, performance cost, response structure, and comparison with a sibling. Nothing an agent needs to call it correctly is 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 coverage is 100%, so the schema already describes each parameter. However, the description adds significant extra meaning: for RESOLVEDESCRIPTIONS it explains the inverted default and the exact performance impact; for RESOLVENAMES it clarifies the single-lookup efficiency and differentiates it from get_access_history. These details directly enrich the agent's understanding beyond the 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 clearly states the tool's purpose: 'Returns card/credential access details for a given card'. It specifies the identifying parameters (ENCODEDNUM + CARDFORMAT) and explicitly distinguishes from siblings by noting that it does not use PERSONID. This leaves no ambiguity about what the tool does and how it differs from similar tools like get_access_history.

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 explicitly states when to use it (when you have ENCODEDNUM and CARDFORMAT) and when not (it has no PERSONID parameter). It also compares with get_access_history on RESOLVENAMES cost, providing a clear basis for choosing between the two. This is explicit usage guidance with 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?

No annotations are provided, so the description carries the full burden. It states 'Returns' which implies a read operation, but it does not explicitly declare it as read-only, safe, or free of side effects. It also does not disclose authentication requirements, error behavior, or any limitations. The mention of wrapping NBAPI GetCardFormats adds implementation detail but not behavioral transparency.

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 purpose and immediately noting the absence of parameters. Every word earns its place; there is no fluff or redundancy. The structure is efficient and easy to scan.

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 annotations, no output schema, and no parameters, the description is the only source of context. It fails to describe the return format, data shape, or potential failure modes. An agent calling this tool would know it returns card formats but not what the response looks like or how to interpret it. This is a significant gap for a tool that could return a list or object with various fields.

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 schema confirms this with an empty properties object. The description explicitly says 'No parameters required', which is clear and sufficient. The baseline for 0 parameters is 4, and the description meets that baseline by reinforcing the absence of inputs.

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 'Returns' and the resource 'card formats configured on the NetBox system', which is specific and unambiguous. It also mentions the underlying NBAPI call, adding implementation context. However, it does not explicitly differentiate from the many sibling get_* tools, though the resource name itself is distinctive.

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 the many sibling getters. It only states that no parameters are required, which is about invocation, not selection. There is no mention of alternatives, prerequisites, or scenarios where this tool is preferred or discouraged.

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 burden. It explicitly discloses that the tool issues only Get commands (read-only), reads from paginated GetTimeSpecGroups, derives a window, and checks whether it is active on the host clock. This goes beyond a simple 'reports the window' statement and gives useful behavioral context.

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, information-dense sentence that front-loads the main purpose and then lists the included details. It is somewhat long but every clause adds meaningful detail about scope, source, and read-only behavior, so it 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 reporting tool, the description is quite complete: it names the managed group, the source commands, the derived window, and the active-now check. It does not describe the output format, but with no output schema and a complex report, a bit more detail on the return shape would help; still, the core calling context is fully covered.

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, so the schema already fully defines the input surface. The description adds value by explaining what the tool reports and how it derives the result, which is more than the empty schema provides. Baseline 4 for zero params 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 states a specific verb ('Reports') and a precise resource ('managed daily recurring unlock window'), and enumerates exactly what is included. It distinguishes itself from the sibling get_unlock_window by specifying the managed 'MCP Daily Unlock Window' group and the derived window, so an agent can tell them apart.

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 this is a read-only reporting tool for the managed daily unlock window and notes it reads from paginated GetTimeSpecGroups. It does not explicitly name alternatives or when-not-to-use, but the detailed scope and read-only note give clear context for when to call it.

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 clearly signals a read-only listing operation ('Lists') and names the wrapped API, but it does not describe pagination behavior, output shape, or failure modes. This is adequate for a simple non-destructive list operation, but not detailed.

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 and resource without filler. The parenthetical endpoint context is useful and non-redundant.

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 list tool with one optional pagination parameter and no output schema, the description plus schema are sufficient to call it correctly. It names the resource, the wrapped endpoint, and the only parameter; enumerating return fields would be helpful but is not necessary for 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?

The schema provides 100% coverage for the only parameter, STARTFROMKEY, with a clear description ('Optional. Pagination cursor to continue listing from a previous call.'). The tool description adds no parameter-specific meaning, so the baseline 3 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 uses a specific verb ('Lists') and a specific resource ('elevators configured on the NetBox system'), and it identifies the wrapped endpoint ('NBAPI GetElevators'). This clearly distinguishes it from sibling get_* 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 usage by naming the resource and action, so an agent can infer it is the tool for listing elevators. However, it gives no explicit guidance on when to use this tool versus alternatives such as get_readers or get_floors.

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 provided, the description carries the full burden of behavioral disclosure. It only states that it 'wraps NBAPI GetEventHistory' and returns historical events, but does not mention that it is a read-only operation, how pagination works (NEXTKEY), or what the response format is. This is minimal transparency for a tool that could have side effects or require specific handling.

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, focused sentence that immediately states the tool's purpose and wraps the underlying API. It is efficient with no filler, front-loading the core action and optional filters. This is exemplary conciseness.

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 that there is no output schema and no annotations, the description should explain the return format, pagination behavior, and any limitations. It only vaguely states that it returns historical events, without describing the structure of the results, how NEXTKEY is used, or whether the operation is read-only. For a tool with four optional parameters and no other structured documentation, this is incomplete and leaves the agent guessing about expected output.

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 coverage is 100% (all four parameters have descriptions in the schema). The description adds little beyond what the schema already provides, merely restating that event name and date range are optional. The NEXTKEY pagination parameter is not mentioned in the description, but the schema documents it. Thus, the description provides marginal additional value, warranting a baseline 3.

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 that the tool returns historical NetBox events and mentions the optional event name/date range filters. It also identifies the underlying API it wraps. While it distinguishes itself by focusing on historical events, it does not explicitly contrast with sibling tools like list_events, which might offer a different scope.

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 retrieving historical event data by stating 'Returns historical NetBox events' and mentions optional filters. However, it does not provide explicit guidance on when to use this tool over alternatives (e.g., list_events) or any exclusions, leaving the agent to infer the appropriate 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?

No annotations are provided, so the description carries the behavioral burden. 'Lists' clearly signals a read-only operation, and 'wraps NBAPI GetFloors' gives implementation context. However, it does not mention pagination behavior, return format, or potential performance concerns, though the STARTFROMKEY parameter in the schema partially addresses pagination.

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 focused sentence that front-loads the core action and resource. It contains no filler or redundant explanation, making it easy for an agent to parse quickly.

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 low-complexity list tool with one optional parameter and no output schema, the description plus the parameter schema is largely sufficient. It could mention pagination explicitly in the prose, but the schema already documents that behavior, so the main gap is minor.

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 fully describes the only parameter, STARTFROMKEY, as an optional pagination cursor, so the schema carries the semantic weight. The description adds no parameter-level detail, but with 100% schema coverage, the baseline of 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 a specific verb ('Lists') with a clear resource ('floors') and scope ('configured on the NetBox system'), so an agent can understand the tool's function immediately. It doesn't explicitly distinguish from sibling tools, but no sibling tool appears to target floors, so the differentiation need is low.

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 the agent needs to list floors, but it gives no explicit guidance about when to prefer this tool over alternatives or when not to use it. There are no exclusions or alternative tool references, but the purpose is straightforward enough that the usage is reasonably inferable.

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 full responsibility for behavioral disclosure. It clearly states the tool is static, makes no controller call, and returns an index for unrecognized topics. This goes beyond a simple 'returns guidance' claim and covers the key behavioral traits an agent needs to know.

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?

Two sentences deliver purpose, behavioral transparency, and usage instructions with zero wasted words. The no-controller-call trait is front-loaded, and the invocation instructions are compact and complete. Every clause 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 single-optional-parameter static reference tool with no output schema, the description covers all invocation paths (with and without topic, unrecognized topic) and the static behavior. Minor gaps remain around the structure of the returned content, but the tool is self-describing reference material, so this is acceptable.

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 the schema already fully documents the topic parameter and its allowed values. The description adds a small amount of value beyond the schema by explaining the behavior for omitted/unrecognized topics ('returns the index instead'), which mirrors the schema but in context. This meets the baseline for covered parameters.

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: 'Returns static reference guidance on this server's S2 NetBox domain knowledge.' It also states 'Makes no controller call,' which clearly distinguishes it from sibling get_* tools that fetch live data. Enumerating the six topics makes the tool's scope immediately obvious.

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?

Explicit usage guidance is provided: call with no topic for an index, or with a specific topic for full content. It also states that an unrecognized topic returns the index instead. It does not name a sibling alternative or an explicit when-not-to-use condition, but the domain-guidance purpose is distinct enough that this is a minor gap.

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 behavioral disclosure. It states the operation is a retrieval ('returns'), which implies a read, and notes it wraps NBAPI GetHoliday. However, it does not describe behavior for an invalid or missing HOLIDAYKEY or the response structure.

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 communicates the tool's purpose, scope, and key parameter without wasted words. The parenthetical wrapper note is short and adds 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?

For a single-parameter getter, the description is sufficient for an agent to select and invoke it correctly. The only gaps are the lack of an explicit not-found behavior and return format, but neither blocks correct use for the common case.

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 coverage is 100% and both the schema and description convey that HOLIDAYKEY is required and unique. The description adds no additional format, source, or usage detail beyond the schema, so the baseline of 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?

States a specific verb, resource, and selection criterion: 'returns the details of a single holiday' for a HOLIDAYKEY. This clearly distinguishes it from the sibling get_holidays, which presumably returns multiple holidays.

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?

Makes clear this is the tool to use when you have a specific HOLIDAYKEY and need one holiday. It does not explicitly name get_holidays as the alternative for listing many holidays, so some inference is required.

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 discloses that the tool returns a comma-separated key string rather than a list of records, that it wraps NBAPI GetHolidays, and that there is no pagination. These are specific behavioral traits that go beyond the schema and significantly aid the agent in predicting output and limitations.

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 no filler. It front-loads the purpose, then provides the return format, the alternative tool, and the parameter note. Every clause earns its place, making it highly efficient.

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 simplicity (no parameters, no output schema), the description covers everything an agent needs: what it returns, how it differs from get_holiday, and its calling constraints. Nothing critical is missing 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?

The tool has zero parameters and the schema coverage is 100% (empty schema). The baseline for zero-parameter tools is 4, and the description adds a note that there are no documented calling parameters, which reinforces the schema. No further parameter explanation is 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?

The description clearly states the verb 'Lists' and the resource 'holiday keys configured on the NetBox system', and immediately distinguishes itself from the sibling get_holiday by noting the return format and that get_holiday is for details. This makes its purpose unmistakable.

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 explicitly directs the agent to use get_holiday per key for details, which is a clear alternative for a different use case. It also notes the lack of parameters and pagination, which informs when to call this tool. However, it does not explicitly state 'use this when you need all keys' or list exclusions, so it falls short of a perfect 5.

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 exist, so the description carries the full burden. It adds useful behavioral context by detailing the nested PARENTLOCATION structure and downstream usage, but it does not disclose permissions, rate limits, pagination behavior, or explicitly state read-only status (though 'Lists' implies it).

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: the first states purpose, the second describes output shape, and the third explains downstream utility. 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 read-only listing tool with two optional parameters and no output schema, the description sufficiently explains output structure and workflow fit. It could briefly mention pagination or ALLPARTITIONS behavior, but the schema already provides parameter semantics, so the description is adequately 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 100%, so baseline is 3. The description adds no parameter-specific meaning; STARTFROMKEY and ALLPARTITIONS are already fully documented in the schema, and the description does not clarify their effects or usage context.

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 and resource: 'Lists the locations configured on the NetBox system.' It also describes the output record structure and names downstream consumers of LOCATIONKEY, making it distinct from the many sibling get_* tools by both name and behavior.

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 clear context that the result is a location tree and that LOCATIONKEY values are used by get_portal_statuses and set_threat_level, implying when an agent would need this tool. However, it does not explicitly exclude alternatives or state when not to use it.

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 provided, the description carries the behavioral burden. 'Returns' implies a read-only operation, but the description does not disclose error behavior, authentication needs, or what happens for an invalid key. This is acceptable for a simple getter but not richly transparent.

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 one compact sentence that states the action, the resource, the input, and the underlying API wrapper. There is no filler or redundancy, and the most important information 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 single-parameter, no-output-schema, no-annotation tool, the definition provides the essential information: what it returns, what input is needed, and how to find that input via a sibling tool. It does not describe the response shape or edge-case behavior, but the tool is simple enough that this is a minor 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%, and the MERCURYKEY parameter is already well documented in the schema as required and as the key to retrieve. The main description only restates 'for a given MERCURYKEY' and adds no additional parameter meaning beyond the schema, so 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 a specific verb ('Returns') and specific resource ('details of a single Mercury panel'), and the word 'single' clearly distinguishes it from the plural sibling get_mercury_panels. Mentioning that it wraps NBAPI GetMercuryPanel adds useful provenance.

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 makes it clear this tool is for retrieving one panel by MERCURYKEY, and the parameter description explicitly tells the agent to use get_mercury_panels to discover keys. It lacks an explicit when-not-to-use statement or comparison to other single-resource getters, but the intended usage is clear.

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 disclosure burden. It compensates by stating the listing behavior, optional filtering, and the failure mode ('empty collection' or FAIL/NOT FOUND) when no Mercury hardware exists. It does not discuss permissions or pagination, but those are less critical for a simple read-oriented list 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 two sentences with no filler, front-loads the core operation, and includes the useful NBAPI wrapper context. Every clause contributes to the agent's understanding.

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 is largely complete for a simple filtered list tool: it names the resource, supports the schema's optional filters, and explains the no-hardware outcome. Since there is no output schema, a success-response shape is not described, but the absence of required parameters reduces invocation risk.

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%, and all four optional parameters already have meaningful descriptions. The prose adds only the collective 'optionally filtered' framing, which is helpful but does not deepen the meaning of any individual parameter beyond the 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 clearly identifies a collection-listing operation with an explicit resource ('Mercury panels'), a system context ('configured on the NetBox system'), and optional filtering. It does not explicitly name or contrast a sibling such as get_mercury_panel, though the plural 'panels' helps distinguish it from the singular sibling.

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 states what the tool does but provides no guidance on when to choose it over alternatives like get_mercury_panel, nor any exclusions or prerequisites. The reader must infer its appropriate use from the purpose 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?

No annotations are provided, so the description carries full responsibility for disclosing behavior. It conveys that this is a read-style operation ('Returns'), scopes the result to a single node, and notes that it wraps NBAPI GetNetworkNode. It does not disclose error behavior, auth requirements, or what happens for invalid keys, which keeps this at a minimum viable level rather than higher.

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 states the action, the resource, the required input, and the wrapped API in a compact and scannable form.

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 single-node getter, the description plus schema provides enough to select and invoke the tool: required key, optional partition, and a discovery route to get_network_nodes. There is no output schema, so a bit more detail about the returned fields could help, but it is not necessary 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?

Schema description coverage is 100%, so the baseline is 3. Both NODEKEY and PARTITIONKEY already have meaningful schema descriptions, including the pointer to get_network_nodes for discovering keys. The main description adds little beyond naming NODEKEY, but the schema already carries the parameter meaning.

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 ('Returns') with a concrete resource ('details of a single network node') and the identifying input ('given NODEKEY'). It clearly distinguishes itself from the sibling get_network_nodes by emphasizing 'single' node retrieval rather than listing.

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 makes the retrieval context clear: use this when you have a NODEKEY and want one node's details. The NODEKEY parameter description additionally points to get_network_nodes for discovering keys, which is a useful routing hint. It does not explicitly state when not to use the tool, but the singular/plural contrast with the sibling is reasonably clear.

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 provided, the description carries the full burden of behavioral disclosure. It only states that the tool lists and optionally filters network nodes, and that it wraps NBAPI GetNetworkNodes. There is no mention of output shape, pagination, filter matching semantics, interaction between filters, or potential error conditions.

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 short and front-loaded with the purposeful verb and resource. The parenthetical "wraps NBAPI GetNetworkNodes" is somewhat redundant and not especially helpful to an agent, but it does not seriously hurt clarity.

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 read-only listing tool with no required parameters and full schema coverage, the description plus schema is minimally viable for invoking the tool. However, no output schema exists and the description does not clarify whether filters are combined, how ALLPARTITIONS relates to PARTITIONKEY, or what the returned list contains, leaving moderate context gaps.

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 five parameters are already documented in the input schema. The description's phrase "optionally filtered" adds general framing but no concrete meaning beyond the schema, so it receives the baseline score.

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 and resource: "Lists the network nodes configured on the NetBox system," which clearly identifies the tool's purpose. It does not, however, explicitly distinguish this list operation from the sibling get_network_node, though the plural naming reduces ambiguity.

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 about when to use this tool versus alternatives such as get_network_node. It mentions optional filtering but does not explain when filters should be applied or when a caller would want the list versus a single node lookup.

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 are absent, so the description carries full responsibility for behavioral disclosure. It only says 'lists auxiliary outputs', which is a read operation, but does not mention safety implications (e.g., read-only nature, no side effects), pagination behavior beyond the parameter, or any potential errors. For a list operation, this is a minor gap, but given the lack of annotations, the description should have at least indicated it is non-destructive and returns a list. The reference to 'wraps NBAPI GetOutputs' adds some context but does not fully disclose behavior.

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, concise sentence that states the purpose and references the underlying API. It is appropriately sized and front-loaded with the core action. No wasted words.

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 (one optional parameter, no output schema, no nested objects), the description plus the schema is nearly complete. However, the lack of any behavioral transparency (e.g., that the operation is read-only and returns a list of outputs) and absence of usage guidance leave minor gaps. With annotations absent, a bit more context would be expected, but for a simple list tool, the current state is adequate.

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 description coverage is 100%, with the single parameter STARTFROMKEY fully described as a pagination cursor. The description does not add further meaning beyond that, so the baseline of 3 applies because the schema already provides sufficient semantics. The description's reference to 'auxiliary outputs' does not directly explain the parameter, but schema coverage meets the burden.

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 lists auxiliary outputs on the NetBox system, a specific verb-resource combination. It also references the wrapped NBAPI endpoint, which helps identify the underlying operation. However, it does not explicitly differentiate from siblings beyond indicating 'auxiliary outputs' as a distinct resource, which is sufficient given the naming.

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 does not explicitly state when to use this tool versus alternatives, but the resource name 'auxiliary outputs' is specific enough that an agent can infer it is for that resource only. It does not mention any context like pagination handling, but the single parameter's schema covers that. No exclusions or alternatives are given, so it's adequate but not 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?

With no annotations provided, the description carries the burden of behavioral disclosure. 'Lists' implies a read-only operation, and the wrapper reference adds context, but the description does not mention return format, pagination, error behavior, or access requirements. It is adequate but not rich.

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 concise sentence that leads with the core action and resource, then adds the wrapper context and parameter note. Every word 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 no-argument list tool, the description is nearly complete: it states what is listed and that no parameters are needed. It does not describe the output shape, but the absence of an output schema and the low complexity make this a minor 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?

There are zero parameters, so the baseline is 4. The description explicitly states 'No parameters required,' which reinforces the empty input schema even though the schema already communicates this.

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 ('Lists') and a clear resource ('partitions configured on the NetBox system'), and it also names the wrapped API ('NBAPI GetPartitions'). This makes the tool's purpose unambiguous and distinct from the sibling get_* 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 usage through its clear purpose, but it does not explicitly state when to use this tool versus alternatives or when not to use it. Mentioning that no parameters are required helps, but there is no explicit 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?

'Returns' makes the read-only nature reasonably clear, and 'wraps NBAPI GetPerson' adds a useful reference. However, with no annotations provided, the description carries the full behavioral burden and does not mention error behavior, authentication needs, or response format.

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?

One sentence with no filler; the core behavior and API wrapper are stated upfront. It earns its place entirely.

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 get-by-ID tool with a complete parameter schema, this is adequate but minimal. It omits usage alternatives, return-shape expectations, and any edge cases, which matters more since there is no output schema and no annotations.

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 four parameters are already documented in the schema. The description adds little beyond naming PERSONID and calling the result 'full,' which is acceptable but not additive.

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 ('Returns') and resource ('full person record') keyed by PERSONID, so an agent can tell this is a direct lookup tool. It does not explicitly differentiate it from sibling search_person_data, though the PERSONID-based lookup strongly implies it.

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 usage context is only implied: an agent would call this when it has a PERSONID and needs the full person record. It provides no explicit when-not guidance or comparison to alternatives like search_person_data.

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, and it excels: it discloses that the payload is passed through unmodified (no decode/resize/truncate), warns about the potentially very large Base64 string, and enumerates the exact error messages for missing or oversized images. It also lists all response fields, giving the agent a complete behavioral picture.

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?

Though longer than average, every sentence earns its place: the core purpose is front-loaded, followed by a critical size caveat, response fields, pass-through behavior, and error cases. The structure is logical and skimmable, 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?

For a single-parameter tool with no output schema and no annotations, this description is exhaustive. It covers the return format, the size concern, the unmodified pass-through, and the exact error conditions. An agent has everything needed to call the tool correctly and handle the response, with no gaps.

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 coverage is 100% — the only parameter, PERSONID, is already documented as required and described. The description adds no new parameter-specific meaning beyond what the schema provides; it mentions PERSONID in the response fields but not in a way that clarifies the input. Baseline 3 is appropriate because the schema already handles parameter semantics fully.

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: 'Returns a person's photo ID image', and names the underlying API it wraps (NBAPI GetPicture). It clearly distinguishes this from sibling tools like get_person, which returns person data rather than the image. The additional detail on response fields and error cases leaves no ambiguity about the tool's purpose.

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 explicitly advises preferring PICTUREURL when only file identification is needed, citing the large Base64 size, which is a concrete when-to-use alternative. Though no sibling tool serves the same function, the guidance about which response field to use is a clear usage directive. It also implies when to expect errors, adding context for the agent's 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 full behavioral burden and discharges it exceptionally: it discloses the inverted opt-out default, the per-call full-table GetTimeSpecGroups fetch cost and why it is fixed, the empty-key behavior (yielding ''), that THREATLEVELGROUPKEY is never resolved and why, and the exact effect of setting RESOLVEGROUPNAMES to false. This is model-level transparency about side effects and costs.

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 dense and longer than typical, but every clause carries information: the inverted default is surprising, the cost implication is decision-relevant, and the threat-level caveat prevents a natural false assumption. Purpose is front-loaded. It could be lightly trimmed, but there is no fluff or 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 2-parameter, single-record getter with no output schema and no annotations, the description covers everything an agent needs: what is returned, the resolved vs raw response shapes, the cost condition, the non-resolvable field, and the escape hatch. Nothing needed for correct invocation is 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 coverage is 100% and the schema's own parameter descriptions are unusually rich, so the baseline is 3. The description adds genuinely new meaning beyond the schema: the 'inverted, opt-out default unlike most optional booleans in this codebase' framing and the 'fixed cost regardless of anything else' rationale. These explain why the default matters in practice rather than restating the mechanic.

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-resource pair — 'Returns the details of a single portal group for a given PORTALGROUPKEY' — and the word 'single' cleanly distinguishes it from the plural sibling get_portal_groups. The NBAPI GetPortalGroup wrapper reference adds grounding. An agent can tell exactly what this does without opening the 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?

The description implies when to use it (retrieve one portal group by key, versus the plural sibling) and gives explicit parameter-level guidance: set RESOLVEGROUPNAMES to false when you want the raw GetPortalGroup response and want to skip the full-table fetch. It does not name alternative siblings or state explicit when-not-to-use conditions, but the context is clear enough that exclusions are inferable.

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 full behavioral burden, and it delivers: it reveals the inverted opt-out default for RESOLVEGROUPNAMES, the exact resolution behavior (new sibling UNLOCKTIMESPECGROUPNAME), the at-most-one-fetch cost, the skip condition, and the permanent non-resolution of THREATLEVELGROUPKEY. This goes far beyond a generic 'list' statement.

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?

Every sentence carries specific operational detail; the first sentence front-loads the purpose, then the description tightens around the non-obvious default and its consequences. No filler or redundant restatement.

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?

Despite lacking an output schema, the description explains the key output difference (added UNLOCKTIMESPECGROUPNAME) and the behavior when the flag is false, while STARTFROMKEY pagination is documented in the schema. Combined with the safety and performance notes, an agent has what it needs to call 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?

Schema coverage is 100% (both parameters documented), so baseline is 3. The description adds crucial semantics for RESOLVEGROUPNAMES — inverted default, foreign-key resolution, cost model, and opt-out behavior — which materially helps an agent choose the right value.

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 the exact operation (lists portal groups) and resource (NetBox portal groups), plus the underlying NBAPI wrapper. This clearly separates it from siblings like get_portal_group (singular) and get_portals.

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 does not explicitly compare against sibling tools such as get_portal_group or get_portals. Its use case is implied through 'Lists portal groups configured on the NetBox system,' but there is no when/when-not or alternative routing.

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 of behavioral disclosure, and it does so excellently. It exposes pagination via STARTFROMKEY/NEXTKEY, the surprising inverted default of RESOLVEDESCRIPTIONS, the fact that GetPortals leaves DESCRIPTION unpopulated, and the extra GetReaders full-table fetch cost per call.

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 dense but information-rich, front-loading the core purpose and pagination behavior. The second sentence packs several important caveats into one long clause; although everything earns its place, it could be structured slightly more cleanly.

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 no output schema and no annotations, the description covers the critical behaviors well: pagination, the single-portal limitation, the default behavior, and the extra fetch cost. It is slightly incomplete on the exact return shape for portal objects, though nested reader fields are partially described.

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% and the schema already documents both parameters, including the RESOLVEDESCRIPTIONS default and behavior. The tool description mostly restates this same information, so it adds little semantic value beyond what the schema provides.

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: 'Lists portals (doors) configured on the NetBox system, each with its nested readers.' It also distinguishes this list-style call from single-portal access by stating 'there is no single-portal filter,' which differentiates it from sibling tools like get_portal.

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 gives clear context for when to use the tool: for listing all portals with nested readers, with no single-portal filter available. It also gives explicit guidance on when to set RESOLVEDESCRIPTIONS to false. However, it does not explicitly name alternatives or state when to prefer find_portals or get_portal.

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 says the tool 'lists' states and wraps NBAPI GetPortalStates, and specifies the return shape. It does not mention authentication, side effects, or pagination, but for a simple list operation this is a reasonable but not fully comprehensive disclosure.

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, front-loaded with the core purpose, and adds only relevant context about the wrapper and the relationship to get_portal_statuses. No filler or redundant information.

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 one optional parameter, no output schema, and no annotations, the description covers the main purpose, return value shape, and how it relates to a sibling tool. It is slightly light on behavioral details such as auth requirements, but the simplicity of the operation and the strong schema coverage keep it nearly 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 100% and the single optional PORTALSTATES parameter has a clear enum description. The tool description does not add parameter-level detail, but it does explain the relationship between the returned STATEKEY values and get_portal_statuses, which is useful context beyond the 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 clearly states the tool lists portal states, identifies the underlying API wrapper, and describes the output as STATEKEY/STATENAME pairs. It also distinguishes itself from the sibling get_portal_statuses by explaining that this tool provides the vocabulary used by that tool's filter.

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 you need the set of valid portal states or the acceptable STATEKEY values for get_portal_statuses. It does not explicitly state when not to use it, but the connection to get_portal_statuses gives clear contextual 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 burden. It states this is a read operation ('Returns the live status'), which implies no mutation, and it discloses the underlying API wrapper (NBAPI GetPortalStatuses). It does not explicitly say 'read-only' or describe side effects, but the nature of a status query makes the safety profile clear. A score of 4 reflects strong implicit disclosure, with room for an explicit read-only note.

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?

Two sentences, no filler. The primary purpose is front-loaded, the return fields are enumerated compactly, and the filtering guidance is efficient. Every clause 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?

With no output schema, the description compensates by listing all fields in each PORTALSTATUS block. It covers the five optional parameters, explains filtering, and points to the relevant vocabulary tools. For a read-only status query with no required parameters, this is complete; nothing an agent needs to call it correctly is 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 coverage is 100% with each parameter already described. The description adds value by grouping the filters (portal, state, partition, location) and cross-referencing the vocabulary tools, which helps an agent understand how the parameters relate. It does not repeat parameter details but enhances their meaning by linking to context.

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: 'Returns the live status of portals (doors)', and immediately clarifies it is the current state, not configuration. It also lists the exact fields returned, making the output shape unambiguous. This distinguishes it from siblings like get_portals (configuration) and get_portal_states (vocabulary) without needing to inspect 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?

Explicitly states the filtering dimensions (portal, state, partition, location) and directs the agent to get_portal_states for STATEKEY vocabulary and get_locations for LOCATIONKEY values. This is clear 'when to use this tool vs alternatives' guidance, naming the exact sibling tools and the condition that selects them.

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?

There are no annotations, so the description carries the full behavioral disclosure burden. It does state the operation ('Returns the details') and identifies the underlying backend call ('wraps NBAPI GetReader'), which adds useful context, but it does not mention read-only behavior, error conditions, or output format.

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 core action, target, and required input. There is no superfluous text or repetition of schema details.

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?

This is a simple one-parameter getter, and the description combined with the schema provides enough information to invoke the tool correctly. However, since there is no output schema, the description could be slightly more explicit about what fields or object shape are contained in the returned 'details'.

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 the parameter READERKEY is already fully documented in the schema. The description repeats the parameter name but does not add any semantic detail beyond what the schema provides, keeping this at the baseline score of 3.

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 the specific action ('Returns the details') and the target resource ('a single reader') with the required identifier READERKEY. The singular 'single reader' clearly distinguishes this from the sibling get_readers tool without needing to inspect 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?

The description implies the usage context: you call this when you have a READERKEY and need one reader's details. However, it does not explicitly state when to prefer it over get_readers or any other sibling, nor does it mention alternative tools for reader-related queries.

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 provided, the description carries the full behavioral burden. It discloses the composite nature, the absence of a server-side reader filter, client-side filtering, SCANWINDOW semantics, the opt-out RESOLVEDESCRIPTIONS default, and the single top-level READERDESCRIPTION field via one GetReaders full-table fetch. This exceeds typical transparency.

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 information-dense but long and run-on, especially the RESOLVEDESCRIPTIONS sentence, which is grammatically tangled and hard to parse. Every clause adds value, but the structure could be split into shorter sentences or bullets to make the key points easier for an agent to absorb.

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?

Despite having no output schema and no annotations, the description covers purpose, composite call behavior, filtering semantics, defaults, and return-field behavior (PERSONID enrichment and READERDESCRIPTION). An agent has enough context to invoke the tool correctly and predict important behavioral quirks.

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 coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining that RESOLVEDESCRIPTIONS is an inverted opt-out default, that SCANWINDOW scans system-wide records rather than a date range, and that READERDESCRIPTION is attached once per call rather than per match. This is useful additional semantic context.

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: 'Returns a single reader's access (grant/deny) history for a given READERKEY', and immediately clarifies it is a composite of GetAccessHistory + GetPerson. It distinguishes itself from the sibling get_access_history by noting the lack of a server-side reader filter and the client-side filtering approach.

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 clear context for when this tool is appropriate: per-reader history, client-side filtering, and SCANWINDOW-based scanning rather than date ranges. It contrasts the inverted RESOLVEDESCRIPTIONS default with get_access_history's behavior, but it could more explicitly state when to prefer this vs get_access_history or another sibling.

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 only says 'returns the details' without specifying the nature of the operation (likely read-only), potential error conditions, or what 'details' encompass. It does mention wrapping NBAPI GetReaderGroup, but that adds no behavioral clarity. The description is too thin to disclose meaningful behavior.

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, focused sentence with no extraneous content. The key fact (returns a single reader group by key) is front-loaded, and the parenthetical implementation detail is supplementary without adding bulk.

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 getter tool with no output schema and no annotations, the description leaves significant gaps: it does not define what 'details' are returned, does not indicate any error behavior, and does not clarify that the operation is read-only. Given the simple single-parameter interface, some of this is inferred, but the absence of return format and usage guidance makes it incomplete for an agent to call 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?

Schema description coverage is 100% for the single parameter READERGROUPKEY, so the schema fully documents the parameter. The description merely restates 'given READERGROUPKEY' without adding format, constraints, or examples beyond what the schema provides, meeting the baseline.

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 it returns details of a single reader group for a given READERGROUPKEY, and explicitly uses 'single' to distinguish from the plural sibling get_reader_groups. The verb 'returns' and resource 'reader group' are specific and 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?

Usage is implied by 'single' and 'given READERGROUPKEY', but the description does not explicitly state when to use this tool over alternatives like get_reader_groups or get_reader. No exclusions or conditions are provided, leaving selection to inference.

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 must carry the behavioral disclosure burden. It only says 'Lists...' which implies read-only, but does not explicitly state safety, pagination behavior, permissions, or side effects. The pagination cursor is mentioned only in the schema, not the description, leaving the agent without important behavioral context.

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 that front-loads the main action. The parenthetical about wrapping NBAPI adds some implementation detail that may not be essential for an agent, but it does not bloat the description. Overall concise and well-structured.

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 only one optional parameter, the description still leaves gaps: it does not indicate what the response contains, whether pagination is required for large lists, or how this tool relates to the singular get_reader_group. The description is too minimal to be fully complete for an agent selecting and invoking the tool.

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 sole parameter STARTFROMKEY has a clear description ('Optional. Pagination cursor to continue listing from a previous call.'). The tool description adds no additional semantic value beyond the schema, so the baseline score of 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 clearly states the action ('Lists'), the resource ('reader groups'), and the system ('NetBox'). It distinguishes itself from sibling tools like get_reader_group (singular) by the plural form, and the parenthetical identifies the underlying API. This is a specific and unambiguous purpose.

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 through the plural 'reader groups' (listing all) but does not explicitly state when to use this instead of get_reader_group or related tools. No alternatives or exclusion criteria are mentioned, so the guidance is only implicit.

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 must carry the behavioral burden. 'Lists' and the NBAPI wrapper make the read-only nature reasonably clear, and the 'no portal-id filter' constraint is useful. However, it does not describe pagination behavior or response format beyond what the schema already provides, so behavioral disclosure is adequate but not rich.

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?

Two concise sentences with no wasted words. The core purpose is front-loaded, followed by the key limitation and the sibling alternative, making it highly scannable for an agent.

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 one-parameter, no-output-schema tool, the description covers what the tool does, its limitation, and the relevant alternative. The missing explicit statement about what the returned reader list contains is a minor gap, but the description is otherwise sufficient 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?

Schema coverage is 100% for the only parameter, STARTFROMKEY, whose description already explains it as a pagination cursor. The tool description adds no parameter-level meaning beyond that, so the baseline of 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 a specific verb ('Lists') and resource ('readers configured on the NetBox system'), making the purpose immediately clear. It also distinguishes itself from get_portals by explicitly noting the absence of a portal-id filter.

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 directly tells the agent when to use this tool vs. an alternative: use get_readers for a flat reader list, and use get_portals to see readers nested under a portal. This is explicit routing with no ambiguity.

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 of behavioral disclosure. It correctly indicates this is a read operation (returns details) and identifies a potential source of confusion (parameter key type). However, it does not disclose return format, error behavior, or authentication needs, which would be helpful for a simple read 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 concise with two sentences. The first sentence states the purpose and the wrapper; the second is a focused caveat about the parameter key. No wasted words, and the key information 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 single-parameter read tool with a clear schema, the description is nearly complete. It addresses a potential ambiguity that could cause errors (the parameter key mismatch) and references a discovery mechanism. The only minor gap is a lack of output format description, but that is not critical since no output schema exists and the purpose is straightforward.

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 the schema already explains the SIOKEY parameter and even recommends using get_sios to discover keys. The description adds no additional parameter semantics beyond clarifying that SIOKEY (not MERCURYKEY) is used, which is a useful nuance but not essential given the schema's 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 tool returns details for a single SIO given its SIOKEY, wrapping NBAPI GetSio. It is distinct from sibling tools like get_sios (which lists keys) and other get_* tools that target different resources.

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 explicitly notes that SIOKEY is used rather than MERCURYKEY, despite a discrepancy in the v2 guide's worked example, and cites the authoritative Calling Parameters list. This directly guides correct usage and prevents misuse, indicating when to trust the description over the guide.

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 provided, the description carries the behavioral burden. It discloses that the request requires MERCURYKEY, that there is no unfiltered listing, and that the response includes a NEXTKEY pagination cursor. This goes beyond a bare 'list SIOs' statement, though it does not detail auth beyond the key or the full response shape.

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. It front-loads the core purpose, then adds the two most important operational facts: the required key and pagination. Every clause earns its place; there is no 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 single-parameter listing tool with full schema coverage, the description covers the essential context: scope, mandatory key, the absence of an unfiltered variant, and the pagination mechanism. No output schema exists, but the description's mention of the NEXTKEY cursor gives the agent the key behavioral detail needed to call it and continue paging.

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 coverage is 100%, so the schema already documents MERCURYKEY. The description adds meaning by clarifying that this key is required and scopes the listing to one panel, and the schema description adds the discovery path via get_mercury_panels. This is useful context beyond the raw 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 states a specific verb ('Lists'), a specific resource ('SIOs attached to one Mercury panel'), and a scope constraint ('one Mercury panel'). It also notes it wraps NBAPI GetSios and explicitly says there is no unfiltered all-SIOs listing, which distinguishes it from any broader listing sibling.

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 makes the usage context clear: this is for listing SIOs for a single Mercury panel, and MERCURYKEY is required. The schema description adds 'Use get_mercury_panels to discover keys,' which provides a concrete prerequisite. It does not explicitly name alternatives like get_sio, but the scope limitation and key requirement are enough guidance.

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