nist_800_53_controls

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

The description goes far beyond the annotations (readOnlyHint and openWorldHint only). It discloses the data source (GitHub OSCAL, not .gov host), the fact that the catalog is live from a moving branch and can shift between releases, the exact semantics of a withdrawn control (statement:null, not an active requirement, see incorporatedInto), that filtering is client-side with exact totalAvailable, and that a download failure throws. This is exemplary behavioral disclosure, directly under a 'HONESTY:' header, and 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?

The description is long but every sentence earns its place. It is front-loaded with the core purpose and retrieval methods, then structured into a clearly labeled 'HONESTY' section covering edge cases and restrictions. The structure is logical: purpose, complement framing, retrieval params, row format, then behavioral caveats. There is no filler or redundancy; density is high and justified by the tool's complexity.

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

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

Given the tool's complexity (5 optional params, nuanced withdrawn-control behavior, external provenance), the description is remarkably complete. It defines the return row fields (id, family, title, status, statement, guidance, incorporatedInto, enhancements), explains the null-statement edge case, notes that the catalog does not encode FIPS-199 baselines, and preemptively addresses failure modes. Even without an output schema, an agent has everything needed to call it correctly and interpret results.

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 meaningfully enriches the parameters. It explains controlId is case-insensitive and zero-padding normalized, family accepts either a 2-letter code or a name substring, keyword is a case-insensitive substring over title+statement, and limit/offset pagination. It also clarifies the output fields (status, statement, incorporatedInto, enhancements) which indirectly informs parameter use (e.g., why keyword searches title+statement). This is more than the schema alone, so a 4 is warranted.

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

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

The description opens with an explicit, specific statement of purpose: 'Look up NIST SP 800-53 Rev 5 security & privacy CONTROLS' — a clear verb+resource pair. It immediately frames the domain ('FedRAMP / CMMC / RMF compliance work') and names complementary siblings ('Complements cve_lookup + cisa_kev_lookup'), so an agent can distinguish it from nearby lookups without inspecting schemas. The retrieval methods (controlId, family, keyword) are enumerated, giving a complete sense of what the tool offers.

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

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

The description provides clear usage context: it is for compliance work and is 'keyless' (no auth), and it notes that 'applicability depends on the system's FIPS-199 impact baseline'. It explicitly says it 'Complements cve_lookup + cisa_kev_lookup' and clarifies that withdrawn controls are not active requirements. However, it does not explicitly state 'use X when Y, use Z when not', so it falls just short of perfect routing guidance, but the context is strong enough to be unambiguous.

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