bidda-compliance

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful behavioral context: the tool returns counts across pillars and jurisdictions, topics are layered on top of pillars, and it is free with no key required. This gives the agent a clear picture of what to expect without needing extra calls.

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?

Four succinct sentences, each contributing unique information: purpose, return value, relationship to pillars, and usage/auth. Front-loaded with the core action, no redundancy or filler.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers selection (what it does), invocation (how to drill down), and behavior (return summary and auth requirements). No significant gaps remain.

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

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

The schema already fully documents the single optional parameter. The description adds value by giving example topic values and explaining the difference between omitting (browse all topics) and providing (drill into one) the topic string, enhancing the agent's understanding of invocation.

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

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

The description clearly identifies the tool as 'Browse the registry by cross-cutting compliance TOPIC' with concrete examples (data breach notification, AI transparency, AML and KYC). It explicitly distinguishes topics from the 39 pillars, preventing confusion with sibling tools like list_pillars.

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

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

Provides clear context for when to use (when exploring cross-cutting topics and their counts), and gives direct instruction 'Pass a topic string to drill into one.' It does not explicitly name alternatives or say 'use this instead of list_pillars', but the pillar relationship implies differentiation.

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 annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context by detailing the output: 'a ranked list of regulations that may apply, plus a risk indicator (LOW/MODERATE/HIGH)'. This goes beyond what 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 description is two sentences, front-loaded with the core purpose ('Pre-flight regulatory check') and includes both examples and outcome. Every sentence contributes meaningful information with no redundancy.

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

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

The tool has a clear output described (ranked list + risk indicator) despite no output schema. It explains the domain (compliance) and primary use case. However, it doesn't discuss limitations or how results interact with other compliance tools, leaving a slight gap in context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value through concrete examples of natural-language action descriptions ('process EU resident biometric data', 'transfer health records...'), clarifying what the action parameter should contain. It also implicitly demonstrates how jurisdiction can be embedded, though the separate jurisdiction parameter is not explicitly described.

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

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

The description clearly states the tool's function: 'Pre-flight regulatory check' with a specific verb and resource. It distinguishes itself from sibling tools by positioning itself as 'The primary tool for runtime compliance gating in autonomous agent workflows'.

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

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

The description implies when to use the tool: before an action, as a 'pre-flight' check. It also asserts primary status for compliance gating, but does not explicitly mention when not to use it or name alternatives. The context is clear, but exclusions are absent.

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 and openWorldHint annotations, the description discloses meaningful behavioral traits: it surfaces actual rules and numbers, does not rank jurisdictions, and requires an authenticated subscription. These are not inferable from the annotations alone and materially affect agent expectations.

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 three tight sentences with no fluff. It front-loaded the core purpose, states a useful boundary behavior, and closes with the authentication requirement. Every sentence contributes new, actionable 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 two-parameter read-only tool, this description is complete enough: it covers purpose, behavior, non-ranking semantics, required context, and expected input style. The absence of an output schema does not hurt because the description adequately signals what the tool surfaces ('real rules and numbers'). An agent can select and 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?

Schema coverage is 100%, so the schema already documents both parameters. The description adds practical semantic value by providing a concrete example topic and clarifying that a free trial key is valid, while the api_key parameter is already thoroughly described in the schema. This justifies the higher side of the baseline.

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

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

The description states a specific verb and resource: compare jurisdictions on a compliance topic side by side, including numeric threshold differences. It also explicitly says it does not rank which jurisdiction is stricter, which clarifies its purpose and distinguishes it from evaluative alternatives. This is clear and unambiguous.

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

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

The description clearly conveys the intended use case: side-by-side jurisdictional comparison of compliance rules and thresholds. It also provides a critical prerequisite: an active Bidda subscription and API key. However, it does not name alternative tools or explicitly say when not to use this tool, so it stops short of full exclusivity 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 indicate a mutating, non-idempotent operation, and the description adds valuable context: the call consumes one key credit, records a verified entry, pins the node to its version and integrity hash, and requires a subscription. This goes beyond the annotation fields without contradicting them.

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

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

The description is information-dense and front-loaded with the core behavior, then adds the key distinguishing guidance and subscription requirement. It is longer than strictly necessary, but every sentence serves a purpose and there is no filler.

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

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

For a composite operation with no output schema, the description covers the operation's effect, the verification semantics, and the prerequisite. It does not describe the return value or failure modes, but that gap is minor given all parameter semantics are already fully documented in the 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 description coverage is 100%, so the schema already documents all nine parameters. The description adds modest extra meaning around api_key (required in practice though schema-optional, with header precedence) and clarifies that node_id is 'the rule to fetch and record,' but it does not deeply enrich most parameters.

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

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

The description names a specific composite verb+resource: fetch the full vault node AND record a verified node_consulted entry, all in a single step. It explicitly contrasts with get_node and record_run_entry, so an agent can immediately tell it apart from its most similar 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 an explicit routing rule: 'Use this instead of get_node when you are inside a run.' It also states the requirement of an active Bidda subscription and an open run, leaving little ambiguity about when this tool is appropriate.

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 annotations already establish that this is not read-only, not idempotent, and not destructive. The description adds useful behavioral context on top: it records which rules were relied on, produces a public verification URL, and confirms the record can later be checked for tampering. It does not explicitly state that every call creates a new persistent record, but the signed, time-stamped, public-URL language is fairly clear.

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 compact and front-loaded: the main action appears first, followed by what the caller gets back, when to use it, and the subscription requirement. Every sentence contributes useful information with no repetition or filler.

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

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

With no output schema, the description correctly explains the return value (record ID plus verify URL) and the authentication requirement, which are the main non-obvious details. It is complete for most calls, but it would be stronger if it also confirmed the public, immutable nature of the created record and explicitly distinguished itself from the control-attestation sibling.

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 parameter descriptions already carry most of the semantic weight. The tool description adds only a high-level note about passing api_key and continuing required subscription, which is useful framing but does not substantially improve on the schema's own parameter details.

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

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

The description clearly identifies a specific verb and resource: it creates a signed, time-stamped attestation record of which Bidda rules were relied on for a decision. It even states the return values (record ID and public verification URL), making the purpose concrete. It does not explicitly contrast itself with the similar sibling 'create_control_attestation', which keeps it from a perfect score.

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 useful context: it is for agents that must keep an audit trail, and it requires an active Bidda subscription or api_key. However, it does not explicitly say when to prefer this over other creation tools, and it never mentions create_control_attestation or any other alternative by 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?

The description adds meaningful behavior beyond annotations: records are tamper-evident, obligations are pinned to current version plus integrity hash at signing time, and the record captures the specific mapping as of that date. This complements the annotations without contradicting them, though it does not describe return values or post-signing 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?

Four sentences, each earning its place: the action and scope, the integrity-pinning behavior, the design-vs-operating distinction, and the subscription/auth requirement. It is compact and front-loaded, though slightly dense rather than minimal.

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 tool with no output schema, the description gives enough context on what the tool does, when to use it, why it is evidence, and what prerequisites exist. It does not explain response shape, but the schema and behavioral description make the call semantics clear.

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 has a high-quality description. The tool description adds context around control, nodes, and api_key but does not need to compensate because the schema carries the full parameter semantics. This meets the baseline for a fully covered schema.

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

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

States a specific action and object: 'Sign a tamper-evident record of one of YOUR OWN controls or policies and the Bidda obligation nodes it maps to.' It clearly scopes this as a design-side control attestation and distinguishes it from run receipts, so an agent can tell this tool apart from generic create or evidence tools.

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

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

Provides clear usage context: this is 'design-side evidence' versus operating-side evidence from 'run receipts.' It also gives an explicit prerequisite: an active Bidda subscription and api_key. It lacks explicit sibling tool names like 'use create_attestation instead,' but the context is sufficient to route the agent correctly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds above-and-beyond context: the hash is optional and omitting it fetches a current fingerprint, the API key can be passed but header is preferred, the batch size scales with plan, and a free trial counts. These details help an agent know how to call it without misusing auth or assuming strict response structure.

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

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

The description is a well-structured block: core invocation first, then input semantics, then auth/billing notes. It is somewhat longer than necessary, but every sentence earns its place. The prose is readable and scannable.

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 tool with two parameters and no output schema, the description sufficiently covers: why to use it, what to pass, what the three possible outcomes are, and how auth behaves. It does not spell out error response shapes or what 'withdrawn' exactly triggers, but that is beyond required scope given annotations and schema coverage.

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 well documents both parameters. The description adds minor extra meaning (hashes are cached integrity hashes; omitting hash fetches current fingerprint; api_key is optional and header preferred), but not substantial new semantics beyond schema. Baseline 3 with slight positive credit 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 ('Check'), resource ('cached compliance rules'), and the tri-state outcome (fresh/drifted/withdrawn), which clearly differentiates it from sibling tools like check_action_compliance or watch_changes. The description tells the agent exactly what to submit (node_id + hash) and what it will receive back.

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?

Describes the clear trigger: before an agent acts on cached rules, it should check drift to know whether re-grounding is needed. It doesn't explicitly name alternatives or say 'use for X, not Y', but the workflow context is unambiguous. The lack of explicit exclusions is a minor gap.

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

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

Annotations already mark the tool readOnly, and the description adds useful behavioral context: it does not rank or determine compliance, it relies on Bidda's dependency graph and registry state, and it requires an active subscription. This meaningfully supplements the annotation-only safety profile.

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

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

The description is dense but efficient: it explains the exact gap semantics, the withdrawn-rule addition, the tool's non-decision role, and the subscription requirement in two sentences. A small amount of editorial emphasis (the parenthetical gap label and dashes) could be trimmed, but no content is wasted.

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 modest complexity and an absent output schema, the description adequately explains the tool's returned content and its scope. It does not detail error conditions or response shape, but for a read-only coverage aid with fully documented parameters, this is a reasonable level of completeness.

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

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

The schema already documents all three parameters at 100% coverage, including depth behavior, node_ids, and api_key header precedence. The description adds only the subscription requirement and a slight incentive to pass api_key, but the schema carries the semantic weight. This aligns with the baseline 3 for full schema coverage.

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

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

States a specific operation (return prerequisite-rule gaps) and names the exact output: covered rules in Bidda's dependency graph that are missing from the team's list, plus covered rules marked withdrawn. This distinguishes it from sibling compliance tools like check_action_compliance and drift_check, which address different compliance questions.

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

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

The description clearly frames the tool as a coverage aid for a qualified reviewer and explicitly excludes ranking or determining compliance. It implies the right context: check missing prerequisite obligations after a team provides its covered rules. It does not explicitly name alternatives or when-not-to-use conditions, so it stops 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?

Annotations declare readOnlyHint=true and openWorldHint=true. The description adds behavioral nuance: open runs produce a 'draft pack' and require api_key, and the pack includes hash-chain integrity checks. No contradictions with 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?

Two sentences: first states purpose and contents, second clarifies sealed/open behavior. All content earns its place, 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?

Given no output schema, the description sufficiently enumerates the pack's components and the sealed/open condition, though it doesn't specify the output format (e.g., zip/PDF/JSON). Sibling context suggests this is a specialized export 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%, with both run_id and api_key described; the description's sealed/open context duplicates the schema's api_key note, adding no new 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?

The description uses the specific verb 'Export' with resource 'run', and enumerates the pack's contents (signed receipt, entries, node roll-up, hash-chain/Merkle check, coversheet), clearly distinguishing it from sibling get_run by its governance-evidence-pack scope.

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

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

It specifies the conditional context: sealed runs are readable by id, open runs require api_key. This gives clear operational guidance, though it doesn't explicitly name alternatives like get_run for simpler retrieval.

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 and openWorldHint, but the description adds valuable context beyond that: it distinguishes between discovery (available dimensions) and full mapping values (vault-gated). This informs the agent about access restrictions and output scope without contradicting 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?

Two sentences, no filler. The first sentence states the core purpose with an illustrative example; the second adds a crucial limitation. Every word earns its place.

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

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

For a single-parameter, read-only tool, the description covers what it returns (mapping dimensions), includes an example, and notes access gating. It lacks an explicit output schema but the description sufficiently sets expectations.

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

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

The schema has 100% coverage for node_id, with a clear description. The tool description provides an example using a node but does not add extra meaning beyond the schema; 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 clearly states the tool's function: returning cross-framework mapping dimensions for a node, with a concrete example (GDPR → CCPA → POPIA). It distinguishes itself from siblings like get_mitre_mapping by covering diverse regulations, standards, and jurisdictions, not just MITRE.

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

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

The description implies when to use this tool: when you need to discover cross-framework mapping dimensions. It adds context that discovery returns dimensions while full values are vault-gated, which clarifies expected results, but it does not explicitly name alternatives or 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 already cover readOnlyHint and openWorldHint, so the bar is lower. The description adds useful behavioral context: default depth 2, max 4, and typical output size (3-8 nodes). It doesn't mention pagination or return format, but with open-world hint and simple params, this is adequate.

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

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

Three sentences, front-loaded with purpose, no wasted words. Each sentence provides distinct value: what it does, why to use it, and operational limits.

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 tool with good annotations and no output schema, the description is complete: it states behavior, use case, depth behavior, and typical scale. No critical gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces max_depth defaults but adds little beyond the schema's own descriptions. The schema already explains node_id and max_depth fully.

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

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

The description clearly states the tool's purpose: 'Walk the prerequisite chain for a compliance node' and 'returns its full dependency tree.' This specific verb+resource combination distinguishes it from siblings like get_node or browse_topics.

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 context: 'Use this to plan a complete compliance posture' and explains the typical need ('unlocking one node usually requires understanding 3-8 upstream nodes'). It doesn't explicitly mention alternatives or when not to use, but the context is sufficient.

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 description claims 'Return all compliance nodes', but the input schema includes a 'limit' parameter with a default of 25 and maximum of 100, meaning the tool does not actually return all nodes by default. This is a significant behavioral misrepresentation. Annotations cover read-only and open-world aspects, but the description itself is misleading about the result set size.

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

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

The description is two sentences long, front-loaded with the action, and every word adds value. It is concise and well-structured without any fluff.

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

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

Despite having good annotations and full schema coverage, the description is incomplete and misleading due to the 'all' claim conflicting with the limit parameter. It does not clarify that results may be truncated or how pagination works, which is essential for a tool that purports to return an entire regulatory surface.

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. The description adds little beyond what the schema already provides for the jurisdiction parameter, and it completely ignores the 'limit' parameter, which is key to understanding the actual behavior. However, it does not need to repeat schema details, so a 3 is appropriate.

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

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

The description clearly states the tool returns all compliance nodes for a jurisdiction, uses a specific verb ('Return') and resource ('compliance nodes'), and lists many jurisdictions. It also distinguishes itself from siblings like compare_jurisdictions, which focuses on comparing rather than returning a bundle.

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 a clear use case: 'Use when an agent enters a new market and needs the full regulatory surface for that geography.' This gives context but does not mention exclusions or alternative tools, so it stops 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?

Beyond annotations (readOnly, openWorld), the description clarifies what counts as a change and advises on scheduling. It does not disclose return format or pagination, but given annotation coverage, this is sufficient for a 4.

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?

Four sentences, each contributing: action/resource, use cases, filtering, and scheduling. No filler. Front-loaded with the verb and object.

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 feed with optional filters, the description covers the core usage and context. It lacks explicit output details, but the absence of an output schema and the tool's straightforward nature make this acceptable. Slight ambiguity about what 'updated' entails prevents 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 already fully documents the two parameters. The description reinforces pillar's purpose ('focus on a domain') but adds no new semantics. 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 clearly identifies the action ('List') and resource ('compliance nodes'), positioning it as the 'regulatory change feed.' It implies a distinction from siblings like search_nodes or watch_changes, but does not explicitly name alternatives, 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?

The description provides explicit use cases: monitoring amendments, new guidance, or new rules, and recommends a scheduling pattern. It does not mention exclusions or alternative tools, so a 4.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe read operation. The description adds context about the return structure (Bidda node plus compliance obligations) and mentions 'Free', providing additional behavioral context beyond 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 concise and well-structured: a catchy metaphor, a clear technical explanation, and a practical bridge statement. Every sentence earns its place, with no wasted words.

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

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

With no output schema, the description explains the return values thoroughly: the Bidda node and the list of compliance obligations across many frameworks. It is sufficiently complete for a simple read-only mapping tool given the schema coverage.

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

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

The schema already provides 100% parameter coverage with detailed examples of valid technique IDs for each framework. The description adds no further parameter semantics beyond reiterating 'MITRE technique ID', so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: given a MITRE technique ID, return the Bidda node plus mapped compliance obligations across multiple frameworks. This is specific and distinguishes it from siblings by emphasizing the unique 'bridge' between SOC and compliance domains.

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 context for when to use this tool—when you have a MITRE technique ID and need compliance mappings. It implies usage through the 'bridge between how SOC teams think and how compliance teams think' phrasing, but it does not explicitly mention alternatives or 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 provide readOnlyHint=true, so the safe-read nature is already known. The description adds value by disclosing the exact summary fields returned (title, pillar, version, last updated, BLUF) and pointing out that the full node (with workflow, schema, citations) is not provided. No contradiction with 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 two sentences, front-loaded with the primary action, and contains no redundant information. Every clause contributes meaning, making it highly efficient.

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

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

Given the tool's simplicity (one parameter, read-only) and no output schema, the description sufficiently explains what the return value contains and what it does not. It sets expectations about the summary and directs users to an external source for the full node, covering all necessary contextual aspects.

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

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

The input schema fully describes the required 'id' parameter with examples and a clear description. The description adds no extra semantic meaning beyond restating 'by its ID'. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get a specific compliance node by its ID.' It specifies the verb (get), the resource (compliance node), and the scope (specific, by ID). It also lists the returned summary fields, distinguishing it from sibling tools like get_dependency_chain or search_nodes.

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 context: use this tool when you have a node ID and need a summary. It explicitly states what the tool returns and notes that the full node is available elsewhere, implying a when-not scenario. However, it does not name alternative sibling tools for cases like finding a node without an ID.

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 and openWorldHint annotations, the description discloses important behavioral details: the owner can read open or sealed runs with an api_key, sealed runs are publicly readable, and the response reports signature validity. This adds meaningful context about access control and output behavior that annotations alone do not 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 description is two sentences, front-loaded with the main action, then adding access and output specifics. Every word contributes to understanding the tool, with no repetition of schema details or fluff.

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

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

Given the tool's simplicity, the annotations, and the 100% schema coverage, the description is quite complete. It explains what is returned (run, entries, signature validity) and the access conditions. However, it does not detail the exact return structure or pagination, but this is not critical for a straightforward fetch tool with no 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?

The schema already covers both parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by linking api_key to the owner role and noting that sealed runs are publicly readable without it, thereby clarifying when the optional parameter is necessary.

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 'Fetch a run and its entries,' using a specific verb and resource that clearly distinguishes it from sibling tools like open_run, seal_run, and record_run_entry. It also clarifies the object being fetched (a run and its entries), which fully identifies the tool's purpose.

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

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

The description provides clear usage context: it explains when an api_key is required (owner reading an open run), and that a sealed run is publicly readable by id. It does not explicitly name alternatives, but the context makes it obvious this is the tool for fetching run data, and the access rules are specified.

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 indicate readOnly and openWorld. The description adds helpful context about the data size and categories (e.g., 10,099 nodes, 39 pillars, MITRE frameworks), which sets expectations without contradicting 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 two sentences and packed with useful specifics (counts, categories, examples). It is not overly verbose but slightly dense; however, it remains concise and well-structured.

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

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

With no output schema, it does not need to explain return values. It adequately describes what the tool lists and gives enough context about the registry's scope, making it complete 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?

There are no parameters, so schema coverage is 100% and no parameter explanation is needed. The description does not need to add anything about parameters; the baseline score is appropriate.

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

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

Clearly states the action (list), resource (compliance pillars), and scope (Bidda Sovereign Intelligence registry) with node counts. It also differentiates from search tools by explicitly recommending this as the first step for discovery.

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 guides when to use: 'Use this first to discover available compliance domains before searching.' This implies that other search-oriented tools should be used after this listing, providing clear usage direction.

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 and OpenWorldHint already cover the non-mutating aspect. The description meaningfully adds that an active Bidda subscription is required and that the feed includes both content changes and withdrawn nodes, which are behavioral details not inferable from the annotations alone.

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 tight, dense sentences. The first sentence explains the resource and its scope, the second anchors the intended use case, and the third states the required subscription. No filler; the most important information is front-loaded.

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

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

The description gives the agent enough to know when to call the tool, what filters can be used, and that authentication comes from an active subscription. It does not spell out any return shape or pagination behaviour, but it has no output schema and the core feed semantics are well described, so it 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 the structured schema already documents the parameters clearly. The description adds only high-level mentions of filtering by time, pillar, or nodes, and the subscription requirement, which is useful but doesn't introduce new parameter-level semantics beyond the schema.

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

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

The description defines the tool as the 'obligation-level change feed,' stating exactly what it returns: primary sources whose content changed or whose node was withdrawn, mapped to affected obligation nodes. It also names the typical user scenario, 'what obligations changed since I last reviewed?', which separates it from broader change or subscription tools.

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

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

It provides a concrete trigger condition ('what obligations changed since I last reviewed?') and identifies the main filtering dimensions (time, pillar, specific nodes). It does not explicitly exclude sibling tools like watch_changes or get_latest_changes, so it stops short of the clearest 'when-not-to-use' 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 indicate readOnlyHint=false and idempotentHint=false, and the description adds relevant context: a new ledger is opened, a run_id is returned, and an active Bidda subscription is required. This goes beyond what the annotations alone communicate and does not contradict them.

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 compact and front-loaded, beginning with the action and core resource definition. Every sentence supplies a distinct, useful fact: purpose, return value, subsequent workflow steps, and authentication requirement — 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?

For a tool with one required parameter and no output schema, the description covers the return value, the subscription requirement, and the surrounding workflow. It could additionally clarify whether opening always creates a new ledger versus reopening one, but the essential calling context is present.

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

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

Schema description coverage is 100%, so the schema already documents agent, label, and api_key. The description adds only general context about api_key being the subscription key; parameter-specific semantics are otherwise already present. This is the appropriate baseline.

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

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

The description states a specific action and resource: 'Open a run ledger' and defines it as a signed, tamper-evident log across a whole task or conversation. It also says the tool returns a run_id and distinguishes itself from workflow siblings by explicitly placing it as the first step before record_run_entry and seal_run.

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 lifecycle guidance: open a ledger, record one entry per turn with record_run_entry, then seal_run to obtain a receipt. It does not explicitly state when not to use this tool or contrast it with get_run and related lookup tools, but the workflow context is clear enough for an agent to pick the right step.

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 and openWorldHint. The description adds value beyond these by disclosing that api_key is required for still-open runs, and by outlining the document composition (reviewed-controls, observations, props). No contradictions.

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

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

The description is a single, dense sentence with a colon-separated list. All content is relevant, though the parentheticals and clause 'the machine-readable format...' add length. Still, it is well-structured and front-loaded with the core purpose.

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

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

With no output schema, the description compensates by listing the key sections of the exported document. It also covers access requirements (api_key for open runs). This is sufficient for an export tool of moderate complexity.

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

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

Schema coverage is 100%, with both run_id and api_key already described in the schema. The description essentially restates these (sealed vs. open run) without adding new parameter-level detail, so it neither compensates nor detracts; baseline 3 is appropriate.

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

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

The description clearly states the verb ('Export'), the resource ('a governed run's evidence'), and the format ('NIST OSCAL assessment-results document'). It distinguishes this tool from siblings by specifying the machine-readable compliance format, making it unambiguous.

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

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

The description provides clear context: this is for producing OSCAL assessment-results for GRC/audit tooling. It also gives a practical condition (sealed vs. open runs) that affects api_key usage. However, it does not explicitly name alternative tools or when not to use it.

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

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

Annotations show readOnlyHint: false, yet the description's 'Get' wording could suggest a simple read. The description does add useful auth context (Bidda subscription and api_key) and the public-history-chain anchoring, but it does not explicitly disambiguate the non-read-only nature of the operation. That leaves the description slightly under-transparent for a tool this potentially consequential.

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 front-load the core purpose, then add a use case and auth requirement. There is little wasted text, though the final sentence about api_key is arguably already encoded in the schema—not severe, just slightly redundant.

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

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

Given there is no output schema, the description still tells the agent what the tool returns (a signed record) and when it is needed. It also conveys prerequisites and the time-input's purpose. That is sufficient for correct selection and invocation.

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

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

The input schema already documents all three parameters with 100% coverage, so the description carries only modest extra semantic weight. It clarifies that as_of targets a past date and that a subscription key is required, but these points are largely derivable from the schema itself.

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

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

The description uses a specific verb ('Get') plus a concrete object ('signed record of which committed version of a rule was authoritative at a specific past date') and a distinctive context ('anchored to the public history chain'). This clearly differentiates the operation from sibling tools like get_node, get_latest_changes, or create_attestation.

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 an explicit trigger scenario: 'useful when an agent must show what a rule said at the moment it acted.' This clearly indicates when to use the tool, although it does not name sibling alternatives or include when-not-to-use guidance, so it falls just 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?

Description adds meaningful non-obvious behavior beyond the annotations: each entry is hash-chained to the previous one, and an active subscription/api_key is required. It does not spell out permanence or failure modes, but the key behavioral traits are disclosed.

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 three-sentence description is compact, front-loaded with the core operation, and includes only high-signal details. Every sentence earns its place.

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

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

Given full schema coverage for all 12 parameters, the description provides enough workflow context: when to use it, what kind of content to record, how integrity works, and the auth requirement. Nothing essential for an agent to select or invoke the tool 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 input schema already covers 100% of parameters, so the baseline is 3. The description adds valuable selection semantics by grouping parameters: consulted nodes, decisions/actions, and user input via note vs input_hash. This helps an agent pick among the many optional fields.

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?

Starts with a clear verb and resource ('Append one entry to an open run') and immediately distinguishes this tool from lifecycle siblings like open_run, get_run, and seal_run. The content scope is also clear: consulted rules, decisions, and user input.

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

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

Provides clear contextual guidance: use it only on an open run and only with an active Bidda subscription. It does not explicitly name alternatives or warn about sealed runs, but the 'open run' framing implies the boundary.

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 idempotentHint annotation, the description adds meaningful behavior: sealing produces a signed receipt with a public verify URL, covers every entry, and requires an active Bidda subscription. It restates idempotency but also explains what that means in a useful, concrete way.

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 compact and front-loaded with the most important action and result, followed by idempotency and subscription requirements. There is no fluff, and every sentence contributes useful information.

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

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

Given the simple two-parameter schema and no output schema, the description provides sufficient context: the input, the effect, and the public verification URL. It could slightly improve by noting that sealing closes the run for further entries, but 'Seal an open run' strongly implies this, so the gap is minor.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds little parameter-level information beyond the schema: run_id is just 'the run_id to seal', and the api_key behavior is already fully detailed in the schema. No additional parameter semantics are needed.

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

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

The description names a specific verb ('seal'), a specific resource ('an open run'), and the concrete outcome ('one signed Run Receipt covering every entry, with a public verify URL'). This clearly distinguishes it from sibling tools like open_run, record_run_entry, and get_run without requiring the agent to inspect schemas.

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

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

The phrase 'Seal an open run' makes the timing obvious, and the idempotency note helps an agent understand it can safely retry on an already-sealed run. It does not explicitly name alternative tools or state the when-not-to-use case, but the context is clear enough for correct selection.

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 indicate readOnlyHint and openWorldHint, so the bar for additional disclosure is lower. The description adds valuable context: it explains the output format (summaries with a one-sentence BLUF) and makes a truthfulness claim ('Every node traces to a primary legal source (no hallucination)'). This goes beyond the annotations without contradicting them.

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 three tight sentences: purpose, output benefit, and illustrative examples. No filler or redundancy. The purpose is front-loaded, and every sentence earns its place by clarifying the tool's function and value.

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 absence of an output schema, the description explains what the tool returns (matching node summaries with BLUF) and its provenance guarantee. It does not mention pagination or sorting, but the schema documents the limit parameter. Overall, it is sufficiently complete for a straightforward search tool with good annotations and schema coverage.

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

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

Input schema covers 100% of parameters, each with descriptions and examples. The description does not add parameter-level meaning beyond the schema; it only provides general use examples. This meets the baseline of 3 but does not exceed 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?

The description starts with a specific verb+resource: 'Search Bidda compliance nodes by keyword.' It clearly distinguishes the tool from siblings like browse_topics or get_node by focusing on keyword search and returning 'node summaries' with a one-sentence BLUF. The examples further clarify the intended use.

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

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

The description implies when to use the tool (when you have a keyword like 'Basel III capital') but does not explicitly provide exclusions or alternatives. It says 'Search... by keyword' and gives examples, but does not contrast with sibling tools like browse_topics or consult_node. Usage guidance is present but 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?

The description discloses meaningful behavior beyond annotations: it says the tool creates an alert subscription, that notifications arrive via email or webhook, and that an API key must be passed. This is useful context that the annotations alone do not provide. 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 a single focused paragraph with no filler. The action, the delivery channel, the watched resource type, and the authentication requirement are all stated clearly. The most important information is front-loaded.

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

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

There are six parameters, no required parameters, a nested channels object, and no output schema. The description could go deeper on return values or on how to combine nodes, pillars, channels, and webhook_url. The schema handles property descriptions, but the description itself does not provide the full operational picture.

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

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

The schema already provides 100% description coverage for all six parameters, and the description does not restate them exhaustively. It does add orientation by mapping parameters to concepts: rule or whole pillar = nodes or pillars, and email/webhook = channels. That is useful but not substantially beyond the schema.

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

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

The description names a specific verb and object: 'Subscribe to regulatory change alerts' and explains what is affected (specific nodes and/or pillars). This clearly distinguishes it from one-shot lookup tools like get_latest_changes and obligation_deltas. The purpose is not tautological or vague.

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 a clear context: use WATCH_CHANGES when regulatory change notifications are needed, and it mentions the prerequisite of an active Bidda subscription. However, it does not explicitly state when NOT to use this tool or directly compare with siblings such as get_latest_changes, obligation_deltas, or check_action_compliance.

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