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

With readOnlyHint=true already declaring this a safe read, the description adds genuine behavioral context: it performs an authentication handshake against the configured controller and returns the API version string (wrapping GetAPIVersion). It does not describe failure behavior (error vs. false) or timeout/retry traits, which would be valuable for a connection check.

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 delivers the purpose, the return value, the underlying implementation, and the parameter situation with zero filler. Nothing could be removed without losing 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 simple, no-parameter, read-only diagnostic, the description covers what it does and what it returns, and there is no output schema requiring further explanation. The only real gap is failure/error behavior, which matters somewhat for a connectivity check but does not block 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?

There are zero parameters and schema coverage is 100%, so the baseline is 4. The explicit note that no parameters are required is accurate and consistent with the empty schema, adding nothing that contradicts it.

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: it confirms server-to-controller authentication and returns the NBAPI version string, naming the underlying GetAPIVersion call. It is unambiguous, but it does not differentiate itself from the sibling diagnostic tools (e.g. ping_app), so an agent must still infer which connectivity check to pick.

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 rather than stated: the description says it confirms authentication, so an agent can infer it is a connectivity/credential check. There is no explicit when-to-use/when-not guidance and no mention of the alternative ping_app sibling, leaving routing 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?

Beyond readOnlyHint=true, the description discloses substantial behavior: case-insensitivity, term-matching rules (every whitespace-separated term must appear), pagination ('reads every page'), the READERKEY join between GetPortals and GetReaders, and the edge case of portals with no reader description. This is rich context an agent cannot get from annotations.

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?

Purpose is front-loaded in the first sentence, followed by matching semantics and implementation detail. Four sentences with little waste, though the GetPortals/GetReaders join detail is slightly deeper than most agents need for invocation.

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 no output schema, the description covers matching rules, edge cases, and data sources well. It stops short of describing the shape of returned portal records, but the matching and scoping semantics are complete enough to invoke 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?

With 1 parameter and 100% schema coverage, baseline is 3. The description adds real meaning about how the query string is interpreted (case-insensitive, multiple whitespace-separated terms, matched against three fields), which goes beyond the schema's example-only description.

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 ('Finds') and resource ('portals (doors)') and immediately clarifies that names are site codes and that the search spans reader names/descriptions. This search behavior implicitly differentiates it from the list-all sibling get_portals without needing to name 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 description explains the search mechanism (matching name/reader name/reader description) and mentions it reads GetPortals and GetReaders, implying use when you need a filtered lookup rather than a full dump. However, it never explicitly states when to use this over get_portals or names the alternative, leaving the routing decision 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?

Beyond the readOnlyHint annotation, it discloses the exact cost model of each enrichment flag (one GetPerson per distinct person; one GetReaders full-table fetch per call, not per record), flags a codebase-wide anomaly (RESOLVEDESCRIPTIONS is the only default-on optional boolean, an inverted opt-out), and states the identity-key constraint. This is materially more than the annotations 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?

The purpose is front-loaded well, but the third sentence is a single bloated construct with nested parentheticals, and it largely restates the RESOLVENAMES/RESOLVEDESCRIPTIONS schema descriptions rather than only adding the rationale. Useful content, but it does not read as tight.

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 9-parameter read-only query tool with no output schema and full schema coverage, the description covers purpose, identity semantics, per-flag cost, and the unusual default behavior. An agent has everything needed to call it correctly and to decide whether to enable enrichment.

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, but the description adds real semantic value the schema lacks: the warning that a person is identified by ENCODEDNUM/HOTSTAMP and not PERSONID (GetAccessHistory has no PERSONID parameter), plus the rationale behind the RESOLVE flag defaults. ORDER/AFTERLOGID/STARTLOGID/MAXRECORDS are left to 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 opening clause gives a specific verb and resource ('Returns historical access (grant/deny) records') and even names the underlying NBAPI operation, so the agent knows exactly what data comes back. It does not explicitly differentiate itself from near-neighbors like get_event_history or get_reader_access_history, which keeps it short of 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 gives clear guidance for the two optional enrichment flags (when to turn RESOLVENAMES on, and that RESOLVEDESCRIPTIONS is opt-out by default), which is genuinely useful. However there is no guidance on when to prefer this tool over sibling history tools, so usage context is only implied.

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 supply only readOnlyHint=true; the description goes well beyond by disclosing the inverted opt-out default, the exact per-call cost (one full-table GetTimeSpecGroups and one GetReaderGroups fetch), the empty-key edge case, and the fact that THREATLEVELGROUPKEY is never resolved. This is exactly the kind of hidden behavior an agent cannot get from structured fields.

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?

Purpose is front-loaded in the opening clause, which is good, but the remainder is a single dense mega-sentence that re-explains RESOLVEGROUPNAMES almost verbatim from the schema. The cost/behavior detail earns its place, but the duplication and lack of sentence breaks hurt readability.

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 does the heavy lifting on return shape by naming the new TIMESPECGROUPNAME/READERGROUPNAME sibling fields and stating the raw response otherwise passes through. It omits error behavior for an invalid or missing ACCESSLEVELKEY, which keeps it short of a 5.

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's RESOLVEGROUPNAMES description already carries the inverted-default note and the resolution mechanics, so the description's parameter content is largely a restatement. It adds no syntax or format detail beyond what the schema already documents, making 3 the correct 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?

States a precise verb+resource: 'Returns the details of a single access level for a given ACCESSLEVELKEY'. The singular 'single' plus the explicit key parameter cleanly separates it from the sibling get_access_levels (plural) and get_access_level_names without the agent needing to open any schema.

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

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

It gives clear guidance on the parameter choice (when to set RESOLVEGROUPNAMES: false to skip fetches), but never states when to call this tool versus the many adjacent siblings (get_access_levels, get_access_level_names, get_access_level_group). The single-vs-list distinction is implied by the name only, so usage is inferred rather than stated.

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

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

The readOnlyHint=true annotation already establishes this is a safe read. The description adds only that it wraps NBAPI GetAccessLevelGroup, with no disclosure of not-found/error behavior, auth requirements, or what 'details' concretely includes. Since annotations carry the safety profile, a 3 is appropriate.

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 front-loaded sentence naming the verb, resource, and key parameter. The parenthetical NBAPI provenance note is minor padding but arguably useful for tracing the underlying API.

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 should ideally sketch the returned shape, but 'the details' stays vague. For a trivial single-parameter getter with full schema coverage and a read-only annotation, it is minimally adequate rather than 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 parameter is fully documented in the schema, so the baseline is 3. The description names ACCESSLEVELGROUPKEY but adds no format, casing, or sourcing guidance 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 verb (Returns) and resource (details of a single access level group) keyed by ACCESSLEVELGROUPKEY. The word 'single' implicitly contrasts with the plural sibling get_access_level_groups, though the sibling is never named explicitly.

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 only implied: 'a single access level group' vs the plural sibling suggests this is the one-at-a-time lookup, but there is no explicit when-to-use, when-not, or named alternative. The agent must infer the routing from the noun number.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds only an implementation note ('wraps NBAPI GetAccessLevelGroups'), which is not behavioral context — no return contents, pagination behavior, or scoping limits are described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the resource is identified before the parenthetical implementation detail. Nothing could be trimmed without losing the core statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list endpoint with full parameter coverage and annotation-declared safety, the description is minimally sufficient. It is silent on what a returned group contains and how it relates to singular/related siblings, which would help an agent disambiguate in a very crowded tool set.

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 two optional parameters (PARTITIONKEY, STARTFROMKEY) are documented in the schema itself, including the odd constraint that only '0' is allowed. The description adds nothing 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?

States a specific verb (Lists) and resource (access level groups) on the NetBox system, so the agent immediately knows what it retrieves. It does not explicitly contrast with the near-identical sibling get_access_level_group (singular) or get_access_level_names, leaving the plural/singular distinction to be inferred.

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 when-to-use, no prerequisites, and no mention of alternative tools despite several plausible siblings (get_access_level_group, get_access_level_names). The listing nature implies a read use case but nothing is stated.

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?

readOnlyHint=true already establishes the safe-read profile, so the description's remaining obligation is to add context it does not: no return shape, no mention that results are paginated via the name cursor, and 'wraps NBAPI GetAccessLevelNames' is an implementation detail rather than agent-useful 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?

A single front-loaded sentence with the verb first and no wasted clauses. The trailing parenthetical about the NBAPI wrapper is of marginal value to an agent but is not bloating.

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-arg, read-only list tool with no output schema, the description is minimally adequate but omits the return format and the pagination story implied by STARTFROMNAME. An agent can call it, but not predict what comes back.

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 PARTITIONKEY and STARTFROMNAME are already documented in the schema. The description adds nothing about either parameter, so 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?

States a specific verb ('Lists') and resource ('access level names') with the scope qualifier 'configured on the NetBox system'. The 'names' framing partially distinguishes it from siblings like get_access_levels/get_access_level, though it never explicitly contrasts the lightweight name lookup against those fuller-object siblings.

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 when-to-use guidance and does not name any alternative. An agent must infer on its own that this is the lightweight name-discovery call versus get_access_levels, and there is no note about prerequisites or pagination-driven repeated calls (the cursor param lives only in the schema).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that: no mention of pagination behavior, authentication requirements, result volume, or what an 'access level' record contains. 'Wraps NBAPI GetAccessLevels' is a source-code note, not operational 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?

A single short sentence with the resource stated up front — no padding. The trailing wrapper parenthetical is marginal but doesn't bloat the definition.

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 list tool with no output schema and fully documented optional params, the description is minimally adequate. It still leaves an agent guessing how it relates to the several near-identically named access-level siblings and what pagination/return behavior to expect.

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 four optional parameters (including both pagination cursors) are already documented in the schema. The description contributes no additional parameter meaning, which is the expected baseline when the schema does the work.

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 ('Lists access levels') and scopes it to the NetBox system, which is clear enough to act on. However it does nothing to distinguish itself from close siblings like get_access_level, get_access_level_groups, and get_access_level_names; the parenthetical wrapper note adds implementation detail rather than differentiation.

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

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

There is no guidance on when to use this tool versus get_access_level, get_access_level_group(s), or get_access_level_names, nor any stated preconditions. The agent must infer usage from the singular/plural name 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?

The readOnlyHint annotation already confirms this is a safe read. The description adds useful behavior beyond annotations: the response is an ALARMS/ALARM collection, and a system with no active alarms returns an empty collection or a documented NOT FOUND. This clarifies return format and error handling, though it omits permission or pagination details.

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 largely front-loaded and efficient, stating the purpose first and then covering filters and response behavior. It is a bit dense with parentheses and a semicolon, but every clause contributes useful information with 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?

There is no output schema, so the description must cover return values, which it does by describing the ALARMS/ALARM collection and the empty/NOT FOUND case. Combined with the fully documented input schema and readOnly annotation, the definition is complete enough for correct invocation, though it could mention authentication or pagination if relevant.

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 each of the six optional parameters is fully documented in the schema. The description lists the same filters (partition, alarm ID, event ID, activity ID, owner) but adds no syntax or format detail beyond what the schema already provides, 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 states a specific verb and resource: 'Returns alarm information from the NetBox system.' It also identifies the underlying API wrapper (NBAPI GetAlarms) and the available filters, making it clearly distinguishable from all sibling tools, which deal with access control, network nodes, and events rather than alarms.

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 stating it returns alarm information with optional filters, but it does not explicitly say when to use this tool versus alternatives. No exclusions or alternative tools are named, so the agent must infer that this is the correct tool for retrieving alarms.

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 only declare readOnlyHint=true, so the description carries real weight and delivers: the inverted, opt-out RESOLVEDESCRIPTIONS default, the exact cost model (one GetReaders full-table fetch per call, not per record), the off-by-default RESOLVENAMES behavior, and where the enriched fields land in the response. This is behavioral detail an agent cannot get from the annotations or schema.

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?

Purpose and lookup-key constraint are front-loaded, and most sentences carry non-obvious information. It is a dense single block, though, and the RESOLVENAMES/RESOLVEDESCRIPTIONS passages substantially duplicate the schema descriptions, which slightly dilutes signal per word.

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 does the work of explaining return shape ('the four fields land on the top level... alongside PERSONID/DISABLED/EXPDATE') plus the enrichment and cost behavior—enough to call it correctly. It does not cover pagination semantics of MAXRECORDS or empty/error results, so it is not fully exhaustive.

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, but the description adds genuine meaning beyond the schema by explaining why RESOLVEDESCRIPTIONS is on by default and what each enrichment costs. The RESOLVENAMES/RESOLVEDESCRIPTIONS sentences largely restate schema text, but the performance rationale and output-placement notes are 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?

States a specific verb and resource ('Returns card/credential access details for a given card') and immediately scopes the lookup key ('Identifies the card by ENCODEDNUM + CARDFORMAT, not PERSONID'), which distinguishes it from person-centric siblings. It also names the underlying primitive (GetCardAccessDetails) and its limitation, so an agent can route correctly 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?

Gives clear context for the RESOLVENAMES choice by contrasting it with get_access_history's costlier per-person lookup, which helps an agent pick the cheaper tool. However it never states an explicit when-to-use/when-not for the tool as a whole versus siblings like get_access_history or get_reader_access_history; the selection guidance is implied rather than spelled out.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds only 'wraps NBAPI GetCardFormats,' an internal implementation detail of no decision value, and says nothing about scope, completeness of the returned set, or 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?

A single short sentence with the core purpose front-loaded. The trailing parenthetical about the NBAPI wrapper is dead weight but does not obscure the main claim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and parameterless, so little is required, but with no output schema the description could have indicated what a 'card format' record contains or whether the list is complete or paginated. It is minimally adequate rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly notes no parameters are required, matching the empty 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 verb and resource: returns the card formats configured on the system. The resource is distinct enough from siblings like get_card_access_details, but the description never explicitly contrasts itself with any alternative, so it stops short of 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?

There is no guidance on when to use this tool versus siblings such as get_card_access_details or get_access_levels. 'No parameters required' is a fact about invocation, not a usage condition, so the agent gets no routing help.

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

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

Annotations already declare readOnlyHint=true, so 'Read-only: issues only Get commands' is largely redundant. The description does add useful behavioral context by noting it reads from paginated GetTimeSpecGroups and describing the components of the returned window plus a live active-now check, which is meaningful given there is no output schema.

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 bloated, comma-spliced sentence with parenthetical nesting and repeated string literals ('MCP Daily Unlock Window' appears twice). It is poorly front-loaded and hard to parse, with the key purpose obscured by the enumeration of internals.

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 must carry the burden of describing return content, and it does attempt to enumerate what is reported. But the enumeration is confusing and omits return shape/pagination details, so it is only partially adequate for a tool whose value lies in its response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which is the baseline-4 case. The description's 'No parameters required' correctly matches the empty input schema, so nothing is ambiguous.

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?

It names a specific verb (Reports) and resource (managed daily recurring unlock window) and enumerates the constituent parts. However, the purpose is buried in a run-on sentence with nested quotes, and it never distinguishes itself from the closely related sibling get_unlock_window, so an agent cannot easily tell the two 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?

There is no explicit when-to-use guidance and no mention of the alternative get_unlock_window or the time-spec/holiday siblings. The only conditional is the vague 'if any', leaving the agent to infer selection criteria.

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?

The readOnlyHint=true annotation already establishes this as a safe read operation, so the description is not carrying the safety burden. Beyond that it only names the upstream wrapper ('NBAPI GetElevators'), which is implementation provenance rather than useful behavioral context such as pagination behavior or result scope; it is consistent with the annotation but adds little.

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 front-loaded sentence with the action and resource first; no padding or restated title. The parenthetical wrapper reference is marginally useful at best but does not undermine the sentence.

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 list tool with one fully documented optional parameter and no output schema, the definition is minimally viable. It still omits what the listing returns and how result sets interact with the cursor, which forces the agent to discover pagination semantics empirically.

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 STARTFROMKEY cursor is fully documented in the schema. The description adds no pagination or format meaning beyond that, 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?

States a clear verb ('Lists') and resource ('elevators') plus the system scope ('configured on the NetBox system'), which is enough to separate it from unrelated siblings like get_readers or get_holidays. It does not differentiate itself from adjacent structural resources such as get_floors or get_partitions, but the resource noun is 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?

There is no when-to-use guidance and no alternative named. Nothing tells the agent whether this is the right call versus get_floors/get_mercury_panels or when a single-elevator lookup would be preferred; usage must be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description is consistent with it ('historical' implies an immutable read). It adds modest context by noting the wrapper origin (NBAPI GetEventHistory) and date-range scoping, but says nothing about pagination behavior, result limits, or what an empty range returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that names the operation, the returned resource, and the filter axes with no filler. The parenthetical wrapper note is the only marginal element, but it is short enough not to hurt.

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 optional-filter history read, the annotations plus a fully-described schema cover most of what an agent needs. However, with no output schema, the description should at least hint at the returned event shape and pagination semantics, which it does not.

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 four optional, self-documented parameters, so the schema already carries the load. The description reinforces EVENTNAME and the date range but adds no format detail (e.g., what 'NBAPI-documented format' actually is, or how NEXTKEY interacts with the range) 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 verb and resource ('Returns historical NetBox events') plus the optional filter dimensions (event name/date range), so the function is immediately understandable. It does not, however, differentiate itself from the sibling 'list_events' or the various access-history tools, leaving the agent to guess the boundary.

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

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

No when-to-use or when-not-to-use guidance is given. With siblings like list_events, get_access_history, and get_reader_access_history present, the description never says which one to pick or under what conditions, so routing is left entirely to inference from the name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the internal note "wraps NBAPI GetFloors", which is implementation trivia rather than behavioral context; pagination behavior implied by STARTFROMKEY is never mentioned.

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 short, front-loaded sentence with the verb and resource up front and no filler. The parenthetical wrapper reference is the only element that arguably does not earn 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 simple read-only list tool with one optional, fully documented parameter, the description is minimally adequate. With no output schema, it could have said more about return shape or whether pagination is supported beyond the cursor.

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 single STARTFROMKEY parameter has 100% schema description coverage, so the schema fully documents it as a pagination cursor. The description adds nothing beyond that, which is the expected baseline when schema coverage is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ("Lists") and resource ("floors") plus the owning system (NetBox), so the operation is unambiguous. It does not distinguish itself from the many other `get_*`/list siblings, so it stops short of 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?

The description gives no when-to-use guidance, no prerequisites, and no alternatives among the many sibling list tools (get_locations, get_elevators, etc.). It only implies usage through the word "Lists", which is not actionable 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds meaningful behavioral context on top: it makes no controller call (so no live state changes or network dependency) and it discloses the fallback behavior for omitted or invalid topics. It stops short of describing content depth or size per topic.

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, front-loaded with the key distinction (static, no controller call) before the usage detail. Minor redundancy in re-enumerating all six topic names already present in the schema, but the structure is tight and skimmable.

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 carries the return-value burden, and it does indicate the two response shapes (an index vs. full topic content). It could say more about what a topic's content covers or its approximate size, but for a one-parameter static lookup this is close to 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 schema already documents the optional topic parameter, the six valid values, and the omitted/unrecognized fallback. The description largely restates that same list, adding no format or semantic detail beyond the schema, 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?

States a specific verb (Returns) and resource (static reference guidance on this server's S2 NetBox domain knowledge), and immediately distinguishes itself from the many controller-calling siblings by noting 'Makes no controller call.' An agent can tell this is a local knowledge lookup, not a data fetch, without opening a 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?

Explicitly covers both invocation modes: no topic returns an index, a topic set to one of the six named values returns that topic's content. It also flags the non-obvious fallback for unrecognized topics, which is exactly the kind of when/when-not guidance that prevents misuse.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds the detail that it wraps NBAPI GetHoliday, but says nothing about failure behavior when the key is unknown or the shape of the returned details. Adequate but thin beyond the annotation.

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 identifying purpose, scope, and the underlying API call; nothing is wasted. It could arguably drop the NBAPI parenthetical, but that is minor.

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 single-record lookup with a fully documented single parameter and annotation-covered safety, the description supplies enough to call the tool correctly. The only real gap is the absence of error/not-found behavior, which is a minor omission for this tool shape.

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?

With 100% schema coverage and only one parameter, the schema already states that HOLIDAYKEY is required and unique. The description restates its role (identifying the holiday) without adding format, case sensitivity, or example values, 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?

States a specific verb and resource ("Returns the details of a single holiday") and scopes it to one record via HOLIDAYKEY, which implicitly separates it from the sibling get_holidays plural listing. It stops short of naming the sibling explicitly, so differentiation relies on the word "single" rather than a direct contrast.

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 the required key: an agent infers this is the tool to call when it already has a HOLIDAYKEY and wants one record. There is no explicit when-to-use/when-not statement and no pointer to get_holidays for enumerating holidays, so the routing 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description still adds meaningful behavior: the return is a comma-separated key string rather than records, and there is no pagination, which prevents an agent from attempting offset/limit 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?

Three short sentences, each carrying distinct load: purpose, return shape plus sibling routing, and parameter/pagination absence. The most decision-relevant fact (key string, not records) 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?

With no output schema, the description fills the gap by describing the return format and the absence of pagination; with zero params and readOnlyHint, nothing else is needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the baseline is 4. The description confirms this explicitly ('no documented calling parameters (no pagination)'), which is useful confirmation rather than mere silence.

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 holiday keys configured on the NetBox system') and explicitly differentiates from the sibling get_holiday by describing itself as a key-only listing. An agent can tell it apart from get_holiday without opening either 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?

Names the alternative ('use get_holiday per key for details') and the condition that selects it, which is clear routing guidance. It stops short of a full when/when-not statement, but the practical fork is unambiguous.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes further and discloses the concrete record shape (LOCATIONKEY, PARTITIONKEY, nested PARENTLOCATION block implying a tree), which is real behavioral context, though it says nothing about pagination behavior or ordering.

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 front-loaded sentences with no filler; purpose comes first, then return shape, then downstream consumers. The parenthetical 'wraps NBAPI GetLocations' is the only marginally expendable content, so not quite a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully carries the return-value burden by describing record fields and the location-tree structure. Pagination and partition-scoping behavior are left to the schema, but nothing needed to call the tool 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 description coverage is 100%, so both parameters (STARTFROMKEY cursor, ALLPARTITIONS enum) are already documented in the schema. The description adds no syntax or semantics beyond that, 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?

States a specific verb and resource ('Lists the locations configured on the NetBox system') and adds the underlying API call (NBAPI GetLocations) for traceability. It is clearly distinguishable from sibling list tools like get_portals or get_partitions, though it never explicitly names what it is not.

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 hints at downstream use by noting that LOCATIONKEY values feed get_portal_statuses and set_threat_level, which implies a reason to call it. However, it gives no when-to-use/when-not guidance, no prerequisites, and no comparison against alternatives such as get_partitions 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?

The readOnlyHint=true annotation already establishes this as a safe read, and the description adds only the fact that it wraps 'NBAPI GetMercuryPanel,' which gives the agent no actionable behavior. No error modes, response shape, or lookup-failure behavior is disclosed, so it contributes little beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero padding; the verb+resource+identifier scope come first and nothing is restated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, read-only lookup with no output schema, the description is adequate: the agent knows what it takes and roughly what it gets. It would be complete at 5 if it hinted at the returned detail or how a missing key behaves, but that 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 single MERCURYKEY parameter is fully documented in the schema, including the discovery hint for get_mercury_panels. The description adds no parameter meaning beyond restating the key requirement, 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 names a specific verb ('Returns the details') and resource ('a single Mercury panel'), and the qualifier 'single' clearly distinguishes it from the plural sibling get_mercury_panels. An agent can select it 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?

Usage is only implied: you call this when you need details of one panel and already hold its key. There is no explicit statement of when this is preferable to get_mercury_panels, though the schema's parameter text ('Use get_mercury_panels to discover keys') partially compensates.

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 readOnlyHint=true already declaring the safety profile, the description adds real behavioral context beyond annotations: it discloses the empty-result case and the FAIL/'NOT FOUND' outcome when no Mercury hardware exists, which prepares the agent for error-shaped responses. It could go further on permission needs or result shape, but the failure-mode disclosure is genuinely useful.

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 short sentences, front-loaded with the core action and followed immediately by the edge-case behavior. No filler, no restatement of the tool name.

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, and the description covers the tricky return case (empty or FAIL/NOT FOUND), which is the main thing an agent needs to interpret results. It stops short of describing what a populated panel entry looks like, but for a simple read-only listing tool this is 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%, so NAME, MERCURYKEY, PARTITIONKEY and ALLPARTITIONS are all documented in the schema with their semantics. The description only says 'optionally filtered' and adds nothing about filter interaction (e.g. whether ALLPARTITIONS overrides PARTITIONKEY), 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?

States a specific verb and resource ('Lists the Mercury panels configured on the NetBox system') and even names the underlying call it wraps, so the agent knows exactly what it does. However, it never distinguishes itself from the singular sibling get_mercury_panel, leaving the list-vs-single choice to inference.

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 phrase 'optionally filtered' hints that filters exist but gives no guidance on when to filter versus list everything, and no prerequisites. It also never points to get_mercury_panel as the alternative for retrieving one panel, despite that sibling being an obvious source of confusion.

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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds only the implementation note "(wraps NBAPI GetNetworkNode)", which is not behaviorally useful to an agent — it says nothing about error handling for missing nodes or the shape of the returned details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no redundancy. The parenthetical wrapper note is mild filler but doesn't disrupt the structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only getter with fully documented parameters this is adequate, but with no output schema the description never indicates what 'details' a node actually contains, leaving the agent guessing at the response.

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%, including the discovery tip for NODEKEY, so the schema does the heavy lifting and baseline 3 applies. The description's "for a given NODEKEY" adds no syntax or format detail beyond what the schema already 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?

States a specific verb ("Returns") and resource ("details of a single network node") keyed on NODEKEY, which cleanly distinguishes it from the plural sibling get_network_nodes. It stops short of naming that sibling explicitly, so it falls just shy of the top tier.

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 "a single network node" — retrieve one node versus the plural listing — but the description itself offers no explicit when-to-use or when-not-to-use guidance. The routing hint to get_network_nodes lives in the schema, not the description.

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?

readOnlyHint=true already signals a safe read, so the bar is lower. The description adds the optional-filter behavior and the underlying NBAPI wrapper, but does not disclose pagination, return volume, or output 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?

A single efficient sentence, front-loaded with the verb and resource. The parenthetical wrapper note is parenthetical and not distracting.

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?

Adequate for a simple read-only listing with no output schema, but leaves pagination, volume, and default-partition behavior unstated, which matter for a list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters including the ALLPARTITIONS enum are already documented. The description only states filtering is optional, adding no syntax or format detail beyond the schema; 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?

States a specific verb (Lists) and resource (network nodes) with scope (configured on the NetBox system, optionally filtered). Distinguishable from the singular sibling get_network_node by explicitly being a 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?

Implied usage is a filtered listing of network nodes, but there is no explicit when-to-use/when-not guidance or routing to alternatives like the singular get_network_node for a single node.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds almost nothing beyond that: it does not say what an 'auxiliary output' is, whether results are filtered or scoped, or how pagination terminates, and the 'wraps NBAPI GetOutputs' note is implementation trivia rather than agent-relevant 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?

A single short sentence, front-loaded with the verb and resource. The trailing parenthetical is dead weight but the description does not ramble.

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 read-only list tool with one fully documented optional param and no output schema, the definition is structurally adequate. It stops short of defining the domain term 'auxiliary outputs' or indicating result scope, which is the main thing an agent would still wonder about.

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?

With one optional parameter and 100% schema description coverage, the schema already explains STARTFROMKEY as a pagination cursor. The description contributes no additional parameter meaning, so the baseline of 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?

States a specific verb ('Lists') and resource ('auxiliary outputs configured on the NetBox system'), which is clearer than a bare name restatement. It does not, however, distinguish itself from the many other list-style siblings (get_portals, get_readers, list_events) beyond the resource noun, and the parenthetical '(wraps NBAPI GetOutputs)' adds no selection information.

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 when-to-use guidance, no prerequisites, and no mention of alternatives among the sibling list tools. The only usage-adjacent hint (pagination) lives in the schema, not the description.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds only the implementation note 'wraps NBAPI GetPartitions' and the redundant 'No parameters required', disclosing nothing about return shape, ordering, or pagination. It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no padding. It is efficient, though arguably too terse to be informative.

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 trivial zero-parameter read tool this is close to sufficient, and the readOnly annotation carries the safety profile. With no output schema, however, the description could reasonably say what a partition record contains, and it offers no usage context against the large sibling set.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to clarify beyond the (accurate) statement that none are required.

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 (Lists) and resource (partitions) plus the source system (NetBox), so an agent knows exactly what it retrieves. There is no partition-related sibling to differentiate from, but the description never routes the agent against the many other get_* list tools in the family.

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 says only that no parameters are required; it gives no context on when to call this versus the dozens of other get_* list tools, nor any prerequisites. Usage is left entirely 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?

The readOnlyHint annotation already establishes that this is a safe read, lowering the bar. The description contributes the scope of the return ('full person record') and traces provenance to the underlying NBAPI GetPerson call, but says nothing about what happens when the PERSONID does not exist or what fields the full record contains.

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 sentence with zero filler, front-loading the return value and the required key before the parenthetical provenance note. Nothing is redundant and nothing needs trimming.

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 carries some burden for describing the returned record; 'full person record' only gestures at it. For a simple ID lookup with a fully documented schema and a read-only annotation, this is adequate but leaves the return shape and not-found behavior unexplained.

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 — including the optional ALLPARTITIONS, WANTCREDENTIALID, and ACCESSLEVELDETAILS flags — are already documented in the schema. The description mentions only PERSONID and adds no format or constraint detail beyond it; 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?

States a specific verb and resource — 'Returns the full person record for a given PERSONID' — which is unambiguous and names the exact identifier needed. It does not differentiate itself from the sibling search_person_data, which is the closest adjacent tool, so it falls short of 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?

Usage is only implied by the presence of the PERSONID parameter; there is no explicit statement of when to use this lookup versus search_person_data or other person-related retrievals. No exclusions or prerequisites are given.

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?

Beyond the readOnlyHint, it discloses payload size ('hundreds of kilobytes of Base64'), the pass-through behavior ('neither decodes, resizes nor truncates'), and verbatim FAIL messages for missing and oversized photos. This is exactly the context annotations cannot carry and it materially changes how an agent should call the 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?

Front-loaded with the purpose, then size warning, then return fields, then error cases — a logical order with no filler. Some sentences are long and the field list borders on restating the response, but each element carries information an agent needs.

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 compensates fully by enumerating the returned fields (PICTURE, PERSONID, PICTUREURL, LASTNAME, FIRSTNAME, LASTMOD), the PICTURE encoding, and every known failure mode. Nothing needed to call or interpret the call 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 single PERSONID parameter is already fully documented in the schema at 100% coverage, so the description adds nothing about parameter format or accepted values. Baseline 3 applies; the 'no picture URL for this person ID' failure note is error behavior, not parameter semantics.

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 ('Returns a person's photo ID image') plus the underlying API it wraps, and the size/prefer-PICTUREURL note makes it immediately distinguishable from generic person getters like get_person. An agent knows exactly what this returns 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?

Explicitly advises 'prefer PICTUREURL when you only need to identify the file', giving a clear condition for avoiding the heavyweight call, and names the failure cases (no photo, oversized image). It does not compare against sibling tools such as get_person or search_person_data, so it stops short of full 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 readOnlyHint already covering the safety profile, the description adds substantial behavior: an inverted opt-out default, a per-call full-table GetTimeSpecGroups fetch with a fixed cost, the new sibling field produced, and the explicit non-resolution of THREATLEVELGROUPKEY. This is well beyond what the annotation conveys.

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?

Purpose is front-loaded and every clause carries information (default, cost, exclusion), so there is little waste. It is dense, though, with heavy em-dash and parenthetical nesting that would read better as short bullet points.

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, the description still sketches return behavior by naming the added UNLOCKTIMESPECGROUPNAME field and what is left unresolved. It omits error behavior for a bad key and does not enumerate the returned fields, but for a two-parameter read tool with readOnlyHint it is otherwise 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 coverage is 100%, so a 3 is the baseline; the description earns above that by explaining the surprising inverted default, the concrete cost of the resolution step, and the fixed-cost reasoning tied to the single-UNLOCKTIMESPECGROUPKEY relationship. It adds real meaning beyond the schema's own text.

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 ('Returns the details of a single portal group for a given PORTALGROUPKEY') and pins the underlying operation ('wraps NBAPI GetPortalGroup'). The word 'single' implicitly but effectively distinguishes it from the plural sibling get_portal_groups.

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?

Gives strong guidance on when to set RESOLVEGROUPNAMES true vs false, including the cost tradeoff. However, it never names an alternative tool (e.g. get_portal_groups for listing, or find_portals) or states when to reach for this tool over its siblings, so tool-selection 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 readOnlyHint already covering the safety profile, the description goes well beyond the annotations: it discloses the inverted opt-out default, the at-most-one-full-table GetTimeSpecGroups fetch per call (not per group), the skip path when all keys are empty, the injected sibling field, and the fact that THREATLEVELGROUPKEY is never resolved. That is unusually rich behavioral context for a 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 purpose is front-loaded in sentence one, but the remainder is a dense single block that largely duplicates the schema's RESOLVEGROUPNAMES text. Much of the length re-covers material already structured elsewhere rather than earning new space.

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 two-parameter read tool with full schema coverage and no output schema, the description is nearly complete on the resolution behavior and its cost. It omits any mention of pagination or how to continue via STARTFROMKEY, which is the one notable 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 coverage is 100%, and the description's account of RESOLVEGROUPNAMES is essentially a restatement of the schema's own parameter description. It adds framing but little genuinely new parameter meaning beyond the schema, 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 first sentence gives a specific verb+resource ('Lists portal groups configured on the NetBox system') and names the underlying API call. It is distinguishable from the singular get_portal_group and from get_portals, though it never states that distinction explicitly.

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 only implied. The description explains when to flip RESOLVEGROUPNAMES to false, but gives no explicit guidance on when to choose this over siblings like get_portal_group or find_portals, nor any prerequisite conditions.

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 carry only readOnlyHint, and the description adds substantive behavioral context beyond it: the inverted opt-out default (unlike other optional booleans in the codebase), the single GetReaders full-table fetch per call rather than per reader, and the exact consequence of opting out (no DESCRIPTION field, no extra call). This is exactly the kind of cost/side-effect disclosure an agent needs before invoking.

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?

Front-loaded with the core purpose and flows logically into pagination then the RESOLVEDESCRIPTIONS nuance. It is dense and heavily parenthesized, and the two schema fields repeat much of the same detail, but every sentence carries real 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?

With no output schema, the description compensates by telling the agent what the return payload looks like (portals with nested readers, reader fields READERKEY/NAME/PORTALORDER, optionally DESCRIPTION) and how pagination terminates. For a two-parameter read tool, nothing needed 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 description coverage is 100%, so both parameters are already documented. The description goes further by explaining the rationale for the unusual inverted default and the performance tradeoff of RESOLVEDESCRIPTIONS (one full-table fetch), which meaningfully supplements the schema text without contradicting it.

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 precise verb+resource ('Lists portals (doors) configured on the NetBox system') and immediately scopes it with nested readers and pagination semantics. The note that there is 'no single-portal filter' implicitly distinguishes it from find_portals and the singular get_* siblings, so an agent can tell what this returns 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?

Gives concrete when-to guidance for RESOLVEDESCRIPTIONS ('set to false to return readers exactly as GetPortals provides them') and explains how STARTFROMKEY continues listing. It stops short of naming sibling alternatives (find_portals, get_portal_group) or saying when this is the wrong tool, so it is clear context without 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?

Annotations only assert readOnlyHint=true; the description adds the upstream origin (wraps NBAPI GetPortalStates) and, more usefully, the exact return structure since no output schema exists. It does not cover auth, pagination, or whether the list is fixed/cacheable, so it is not fully 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 tightly packed sentences, front-loaded with what is listed and followed immediately by the return shape and sibling relationship. No filler or restatement of the tool name.

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 supplies the return shape (STATEKEY/STATENAME pairs) and the consumer relationship to get_portal_statuses. Combined with a fully documented single parameter and a read-only annotation, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single PORTALSTATES enum is fully documented in the schema (partition scoping for TRUE vs omitted). The description adds no parameter detail, 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?

States a specific verb and resource (lists the portal states NetBox defines) and pins down the return shape as STATEKEY/STATENAME pairs. It explicitly distinguishes itself from the sibling get_portal_statuses by framing itself as the vocabulary the latter reports against.

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 names the sibling it relates to and the condition that makes it useful (to interpret or filter get_portal_statuses' STATEKEY). It stops short of an explicit when-not-to-use statement, but the routing intent is clear without opening either schema.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds the genuinely behavioral trait that this is live/current state rather than stored configuration, and notes it wraps NBAPI GetPortalStatuses. It omits auth needs, pagination, and large-result behavior, so it is helpful but not complete.

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?

Front-loaded with purpose and the config-vs-status distinction, followed by the filter summary and vocabulary routing. The PORTALSTATUS field enumeration is long but justified since no output schema exists; slightly dense overall.

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, enumerating the returned PORTALSTATUS fields (PORTALKEY, STATEKEY, STATENAME, etc.) is exactly the missing context an agent needs, and the vocabulary cross-references close the loop on filter values. Only pagination/partition-default and auth expectations are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter already documents itself and cross-references the vocabulary tools, so the schema does the heavy lifting. The description only summarizes 'filter by portal, state, partition or location' and never mentions ALLPARTITIONS, adding marginal meaning 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 verb and resource ('Returns the live status of portals') and explicitly carves out scope versus the sibling: 'the current state of each door, not its configuration'. An agent can distinguish this from get_portals without opening either 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?

Gives concrete usage context ('Filter by portal, state, partition or location') and routes the agent to sibling tools for parameter vocabularies (get_portal_states for STATEKEY, get_locations for LOCATIONKEY). It does not state an explicit when-not or name get_portals as the configuration alternative, so it falls short of a 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds only that it 'wraps NBAPI GetReader,' an implementation detail that does not help invocation, and says nothing about not-found/error behavior or what happens with an unknown key.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the verb and resource up front. The parenthetical wrapper note is the only arguably non-earning clause, but the overall size is 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?

For a simple one-parameter read tool, the essentials are covered. With no output schema, however, the description does not indicate what 'details' are returned (credential format, location, status), leaving the return shape unspecified.

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 documents READERKEY as required and unique. The description repeats the parameter name but adds no format, source, or lookup guidance beyond it, so 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?

Clear verb (returns details) plus resource (a single reader) keyed by READERKEY. The word 'single' implicitly distinguishes it from the sibling get_readers, but the differentiation is left for the agent to infer rather than stated.

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 only implied: 'a single reader' suggests this is the per-item companion to get_readers, but there is no explicit when-to-use or when-not-to-use statement, and no alternative is named.

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 only readOnlyHint available, the description carries real weight: it discloses the client-side scan over system-wide records, the SCANWINDOW fallback instead of a date range, and the cost of the RESOLVEDESCRIPTIONS path (one GetReaders full-table fetch). These are genuine operational traits an agent could not infer from annotations.

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 purpose is front-loaded and every claim is substantive, but the body is one dense run-on that re-explains RESOLVEDESCRIPTIONS details the schema already states verbatim, and the inverted-default caveat is buried mid-paragraph. It is informative but not tightly 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?

No output schema exists, and the description supplies the important return-shape nuance (PERSONID enriched to a name, single top-level READERDESCRIPTION). It does not describe ordering guarantees or what a match record otherwise contains, leaving a modest gap for a history-returning 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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: SCANWINDOW counts most-recent system-wide records rather than the reader's own, and READERDESCRIPTION is attached once at the top level rather than per match, with the reasoning. That is real semantic enrichment over the field text.

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 — 'Returns a single reader's access (grant/deny) history for a given READERKEY' — and explicitly frames itself as a composite wrapper over NBAPI GetAccessHistory + GetPerson. It is clearly distinguishable from the sibling get_access_history by scoping to one reader.

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?

Explains the key selection context: GetAccessHistory has no server-side reader filter, so this tool filters client-side, which tells an agent when this wrapper is the right call and hints at its cost. It references get_access_history as the sibling precedent but never states an explicit when-not-to-use rule or a preferred alternative.

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 declare readOnlyHint=true, so the safety profile is covered. The description adds only the 'wraps NBAPI GetReaderGroup' implementation note, which describes internals rather than behavior; it says nothing about error handling for a bogus key or what fields are returned.

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 front-loaded sentence with the key constraint and identity clear. The redundant parenthetical is the only wasted content.

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-param read tool this is nearly adequate, but it omits any return-shape hint (no output schema), error behavior for invalid keys, and the sibling routing an agent needs to distinguish it from get_reader_groups.

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 single parameter is documented there as required and unique. The description only echoes the parameter name, adding no format, casing, or sourcing guidance 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 verb (Returns) and resource (details of a single reader group) with the identifying key, distinguishing it from the sibling get_reader_groups (plural). The parenthetical wrapper note adds no purpose but doesn't obscure 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?

No when-to-use guidance and no explicit routing to get_reader_groups for listing or get_reader for the hardware itself. The singular/plural sibling distinction is only implied by the word 'single'.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only 'wraps NBAPI GetReaderGroups', an implementation detail rather than useful behavior; it does not mention pagination behavior even though a cursor parameter exists.

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 efficient sentence that front-loads the verb and resource. The parenthetical wrapper note is marginally wasteful but brief, so it doesn't harm readability.

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 list tool with a fully documented single parameter and no output schema, the definition is adequate. It could be stronger by noting pagination intent or routing to the singular sibling, but nothing critical 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 description coverage is 100%, so the single STARTFROMKEY parameter is already fully documented in the schema as a pagination cursor. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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 ('Lists') and resource ('reader groups') with a location qualifier ('configured on the NetBox system'), so the agent knows exactly what it retrieves. It doesn't explicitly differentiate itself from the singular sibling get_reader_group, but the plural scope is reasonably inferable.

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

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

There is no guidance on when to use this versus the nearby get_reader_group or get_readers siblings, and no prerequisites or exclusions are stated. Usage is only implied by the word 'Lists'.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only marginal context ('wraps NBAPI GetReaders') and the absence of a filter; it says nothing about result size, pagination behavior, or ordering beyond what the schema's cursor parameter implies.

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 short sentences, zero filler, and the scoping/limitation statement is front-loaded right after the purpose. Nothing extraneous.

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 read-only list tool with one optional parameter and no output schema, the description covers purpose, the key limitation, and the alternative route. Nothing essential for invocation is missing; only richer return-shape detail is absent, which is acceptable without an output schema.

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 sole parameter (STARTFROMKEY) is fully documented in the schema as a pagination cursor. The description adds only the negative statement that no portal-id filter parameter exists, which marginally clarifies the parameter surface but adds no syntax or format detail. Baseline 3 applies.