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?

The annotations include readOnlyHint=true and openWorldHint=true, so the safety profile is already established. The description adds meaningful behavioral details beyond that: it surfaces real rules and numbers (data freshness) and explicitly states it does not rank, setting expectations for output behavior. It also discloses the authentication requirement, which is a behavioral constraint.

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 sentences long, each earning its place: the first defines the core action, the second clarifies output characteristics and non-ranking behavior, and the third gives a usage prerequisite. There is zero redundancy 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?

For a two-parameter tool with no output schema, the description covers all essential aspects: what it does, example usage, non-ranking caveat, and authentication requirement. It doesn't describe the exact return format, but that is not critical given the simplicity and the 'openWorldHint' annotation. It is well-rounded and adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning to the parameters beyond what the schema already provides; the 'topic' parameter is well-described in the schema with an example, and api_key is also documented. The example about 72 vs 30 days illustrates the tool's output rather than parameter format.

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

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

The description opens with a specific verb ('Compare') and resource ('jurisdictions'), and clarifies the scope ('a compliance topic, side by side'). It distinguishes itself by explicitly stating what it does not do ('does not rank which jurisdiction is stricter'), which is a clear differentiator from potential sibling tools like check_action_compliance or get_jurisdiction_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 gives a clear context for when to use the tool (comparing juridictions on a compliance topic) and a when-not (does not rank stricter jurisdictions). It does not explicitly name alternative sibling tools, but the context is sufficiently clear. The subscription requirement is also stated, which is a practical prerequisite.

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 key behaviors beyond annotations: it consumes one call on the key, records a verified entry, pins the node to its version and integrity hash, and requires a subscription. These are material side effects and constraints that go beyond the provided annotations, which only indicate non-read-only, non-destructive, non-idempotent, and open world.

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 succinct (~80 words) and well-structured, moving from what the tool does, to why it matters, to when to use it. Every sentence adds necessary operational or usage context 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 a compound side effect, no output schema, and 9 parameters, the description covers the operation's purpose, side effects, cost, usage context, and prerequisites. The schema handles parameter details, so the description is fully adequate for an agent to invoke the tool correctly.

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

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

The input schema already provides complete descriptions for all 9 parameters (100% coverage). The description mentions api_key and run_id requirements but does not add meaningful new semantics beyond what the schema states, 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 clearly states the tool performs a two-part action: fetching the full vault node and recording a verified node_consulted entry on an open run. It explicitly distinguishes itself from get_node, making the tool's purpose unambiguous and differentiating it from sibling tools.

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

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

The description explicitly instructs to use this tool instead of get_node when inside a run, and notes the prerequisite of an open run and active Bidda subscription. This provides clear when-to-use and alternative 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, but the description adds value by disclosing the subscription requirement ('Requires an active Bidda subscription: pass api_key') and the return behavior (record ID and public verify URL, confirming immutability). This goes beyond the structured hints.

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 sentences, front-loaded with the primary purpose, then returns, then usage guidance and auth. It avoids fluff and is appropriately sized for the complexity of the tool.

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

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

Given no output schema exists, the description compensates by explaining the return values (record ID and verify URL). It also covers the purpose and authentication. For a 5-parameter tool with clear schema coverage, this is sufficient, though it could mention edge cases or limits (e.g., max 50 nodes is only in schema, not description).

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 reinforces the api_key requirement and explains the overall purpose of 'nodes' but does not add substantial semantic detail beyond the schema's own field descriptions.

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

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

The description clearly states it creates a signed, time-stamped record of which Bidda rules were relied on for a decision, and mentions return values (record ID, verify URL). This distinguishes it from generic 'create' tools, though it does not explicitly contrast with the sibling tool 'create_control_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?

It provides a clear usage context: 'Useful for agents that must keep an audit trail of what they checked.' This implies when to use the tool, but it does not explicitly mention when not to use it or describe alternatives such as 'create_control_attestation'.

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 that signing pins each obligation to its current version and integrity hash at signing time, and that the record is tamper-evident. It also notes the subscription requirement. This adds context beyond the annotations (which state it's not read-only and not idempotent) 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 sentences, with the main verb and object in the first sentence. Every sentence adds value (purpose, behavior, context/subscription), 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?

Given the tool's moderate complexity (9 params, 4 required) and no output schema, the description covers purpose, behavioral nuances, and a prerequisite. It doesn't describe return values, but this is not critical for an attestation creation tool. Overall it is complete enough for an agent to select and invoke the tool.

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

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

Schema coverage is 100%, so baseline 3; the description adds meaning by explaining that nodes are pinned to current version + integrity hash, which clarifies the nodes parameter. It also frames the statement as 'what the control does or asserts' in the context of design-side evidence, enhancing the schema definitions.

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 'Sign a tamper-evident record of one of YOUR OWN controls or policies', which clearly identifies the action (sign/create) and the resource (control attestation). It distinguishes itself from run receipts ('run receipts are the operating-side evidence') and explicitly scopes to the user's own controls, differentiating it from the sibling 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 explicitly contrasts design-side evidence with operating-side run receipts, telling the agent when this tool is appropriate. It also states the prerequisite of an active Bidda subscription and the need to pass api_key. However, it doesn't explicitly name an alternative tool for when not to use this, beyond the implicit run receipts contrast.

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 as readOnly and openWorld, so safety is disclosed. The description adds meaningful behavioral context: it explains that the tool compares submitted hashes to current state, and returns a per-rule status (fresh, drifted, withdrawn). This goes beyond annotations by describing the semantic output categories and the workflow of re-grounding. It does not contradict 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 three sentences, with the purpose stated first. It efficiently covers purpose, usage, return value, and plan availability. The only minor extra is the tier/pricing note, which is useful but not strictly necessary. Overall it is well-structured and not verbose.

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

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

Given a simple two-parameter tool with no output schema, the description is quite complete: it explains what the tool does, why it exists, how to invoke it, and what results to expect. The only missing elements are explicit error scenarios or rate limits, but the degree of completeness is sufficient for this tool's 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% for both parameters, so the schema already documents anchors and api_key, including that hash is optional. The description restates the parameters in workflow language ('Submit the node_id and the integrity hash you stored'), which adds slight context but does not materially enhance the meaning beyond the schema's own descriptions. 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 tool's purpose: check whether cached compliance rules are still current. It names the specific verb ('check') and resource (compliance rules the agent cached), and distinguishes itself from sibling tools like 'watch_changes' or 'check_action_compliance' by focusing on drift detection for grounded rules. The return statuses (fresh, drifted, withdrawn) make the function 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 gives explicit context for when to use the tool: before acting on law, to re-ground if stale. It also notes that the tool is included with every API tier and batch size scales with plan, which are helpful operational cues. However, it does not explicitly name alternative tools or say when NOT to use this tool, so it falls slightly 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 already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context beyond this: it requires an active Bidda subscription via api_key, and it clarifies that the tool is a 'coverage aid' that does not perform compliance determination. This adds functional limitations and auth requirements not present in 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 front-loads the main purpose. The first sentence is long and dense, but every clause adds relevant detail (gaps, withdrawn rules, non-ranking). It is efficient without being terse.

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

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

The description covers the return contents (missed prerequisites and withdrawn rules), the limitation (no compliance ranking), and the auth requirement. There is no output schema, but the description adequately explains the output's substance. Missing details like pagination or error behavior are minor given the read-only, focused scope.

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 parameters (nodes, api_key, depth) have descriptions in the schema. The tool description adds minimal extra meaning, mostly restating the purpose of nodes and api_key usage. The baseline of 3 applies because schema carries the burden.

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

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

The description clearly states the tool's function: it returns prerequisite rules that were missed plus withdrawn covered rules, using specific language like 'return the prerequisite rules' and 'gaps'. It also distinguishes itself by noting it does not rank or determine compliance, setting it apart from sibling tools like check_action_compliance or drift_check.

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 context on when to use it ('Given the compliance rules a team says it covers') and explicitly states what it does NOT do ('does not rank or determine compliance'), giving an implied 'when-not-to-use'. It does not name alternative tools, but the exclusions are clear enough to guide 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 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 mark the tool read-only and open-world. The description adds useful context about the dataset (10,108 nodes, 39 pillars, example domains) and confirms the output includes node counts. However, it does not detail return format or edge cases. It doesn't contradict 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 achieve purpose, usage, and context without redundancy. Each sentence adds information: the first states what it does, the second adds dataset size and examples.

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

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

For a simple listing tool with no parameters and no output schema, the description is sufficient. It states what is returned (pillars with node counts), when to use it, and provides examples. No behavioral caveats are necessary for a read-only 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?

The tool has no parameters, so the input schema is fully covered. The baseline for 0 parameters is 4, and the description doesn't need to elaborate further.

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

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

The description uses a specific verb 'List' with a clear resource 'compliance pillars in the Bidda Sovereign Intelligence registry' and adds 'node counts' as output detail. It distinguishes from sibling tools like search_nodes by positioning itself as a discovery endpoint. It also clearly scopes to 'all' pillars with no filters.

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

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

The description explicitly says 'Use this first to discover available compliance domains before searching,' giving clear when-to-use guidance. While it doesn't name specific alternative tools, the mention of 'searching' and the sibling tool names imply search_nodes as the next step. It could be more explicit about 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?

Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful behavioral context: it includes withdrawn nodes, maps changes to obligation nodes, and requires an active subscription with an api_key. These are non-obvious details that affect how an agent should invoke and interpret 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?

The description is two sentences long, front-loaded with the core purpose, and every clause adds useful information. It avoids fluff and clearly covers what, how, when, and a key prerequisite.

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 change feed with five parameters and no output schema, the description provides enough context: it explains the domain (obligation changes), the mapping behavior, the filters, and the auth requirement. It does not detail return format, but the absence of an output schema makes this less critical.

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 provides full descriptions for all 5 parameters (100% coverage), so the description adds little beyond what the schema says. It mentions filterability by time, pillar, or nodes, but that is directly reflected in the schema, so no substantial extra semantics are provided.

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 this as an obligation-level change feed that maps content changes in primary sources to Bidda obligation nodes, and distinguishes it from sibling tools like get_latest_changes by specifying 'obligation-level'. It also provides a concrete use case ('what obligations changed since I last reviewed?').

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

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

The description explicitly states when to use the tool with the phrase 'Use it to answer...' and notes that an active Bidda subscription is required. It does not name an alternative or when not to use it, but the context is clear enough for a user to decide between this and similar change-feed tools.

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, the description adds key behavioral details: it creates a signed tamper-evident ledger, returns a run_id, and requires an active Bidda subscription with api_key. This is consistent with annotations and provides context about prerequisites and non-read-only nature.

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

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

Three sentences, each with a distinct purpose: definition, workflow, and requirement. No unnecessary words, information is front-loaded 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?

Given no output schema, the description adequately covers the return value ('Returns a run_id'), the workflow, and the prerequisite. It is complete enough for an agent to select and invoke the tool 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 description does not need to elaborate on parameters. It does mention api_key but adds no meaning beyond the schema's own description. 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 action ('Open a run ledger') with a specific resource and purpose ('a signed, tamper-evident log of what an agent does'). It distinguishes itself from siblings by explicitly referencing the workflow with 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?

Provides clear workflow context: 'Record one entry per turn with record_run_entry, then seal_run to get a single signed Run Receipt.' This tells the agent when to use this tool (first step) and what to do next, though it does not explicitly state when not to use it.

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

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

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?

The description says 'Get', implying a read-only operation, but annotations declare readOnlyHint=false, indicating the tool may have side effects or modify state. This contradictions misleads the agent about the tool's behavior. Additional context about subscriptions and anchoring does not mitigate this fundamental conflict.

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 function, and contains no fluff. The second sentence adds the use case and a crucial prerequisite. It is 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?

For a simple 3-parameter tool with no output schema, the description covers the purpose, the use case, and the auth requirement. It does not specify the return format in detail, but the notion of a 'signed record' combined with 'anchored to the public history chain' provides sufficient context for an agent to understand the expected result.

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

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

Although the input schema covers 100% of parameters, the description adds meaningful semantics by clarifying that node_id identifies 'a rule' and as_of refers to 'a specific past date' for which the authoritative committed version is needed. It also reinforces the api_key requirement.

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 with a specific verb ('Get') and a well-defined resource: 'a signed record of which committed version of a rule was authoritative at a specific past date'. This uniquely distinguishes it from sibling tools like get_node or get_latest_changes.

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 an explicit use case: 'Useful when an agent must show what a rule said at the moment it acted.' It also mentions the prerequisite of an active Bidda subscription. However, it does not mention alternatives or when not to use, so it lacks explicit 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?

The annotations already flag this as a non-read, non-idempotent mutation (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds valuable context beyond annotations: entries are hash-chained to previous ones, and a valid api_key with active subscription is required. It does not describe failure modes or side effects beyond the chain, but it covers the essential behavior.

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

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

Two sentences, front-loaded with the verb and resource. The first sentence explains scope and components; the second reveals two critical traits (hash-chaining and subscription necessity). No filler or repetition of schema details; every clause earns its place.

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

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

Given 12 parameters, no output schema, and minimal annotations, the description provides a coherent summary: what an entry is, how it is recorded, and what is required. It does not mention return values or behavior if the run is not open, but the core usage is sufficiently specified for an agent to operate effectively.

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, the baseline is 3. The description adds meaning by mapping 'which Bidda rules the agent consulted' to nodes, 'what it decided' to decision, and 'end user's input (as text via note, or privately as input_hash)' to note/input_hash. It also highlights the required api_key parameter. This enriches the schema without needing to restate every parameter.

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

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

The description opens with a specific verb+resource: 'Append one entry to an open run,' and enumerates the entry contents (rules consulted, decision, user input). This clearly distinguishes it from sibling tools like open_run (create) and seal_run (finalize), making the tool's role 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 states a clear use case ('append one entry to an open run') and a prerequisite ('Requires an active Bidda subscription: pass api_key'). It does not explicitly mention when to use alternatives, but the distinction from open/close/read tools is implied and sufficient for an agent to select this tool when appending to an existing run.

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 details beyond annotations: idempotent behavior returns the same receipt, requires an active Bidda subscription, and produces a public verify URL. These enrich the agent's understanding 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, front-loaded with the action and outcome, followed by idempotency and prerequisites. 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?

The description covers the tool's core behavior, idempotency, and requirements. It lacks an explicit statement about error conditions (e.g., run already sealed, not open) but provides enough for a well-scoped seal 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 the schema fully documents both parameters. The description only reiterates 'pass api_key' without adding new meaning, so 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?

The description uses a specific verb 'Seal' and clearly defines the action: sealing an open run into a signed Run Receipt covering every entry, with a public verify URL. This distinguishes it from sibling tools like open_run or get_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 implies the use case: you seal an open run after entries are recorded. It also notes idempotency and the subscription requirement, giving clear context. However, it doesn't explicitly compare to alternatives or state when not to use it.

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

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

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 explains the behavioral model: watch nodes/pillars, receive notifications via chosen channels, and requires a valid subscription. It aligns with annotations (readOnlyHint=false, idempotentHint=false) without contradiction, adding context about the subscription prerequisite and notification mechanism 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 primary purpose and followed by the key requirement. No redundant information or filler; every clause contributes to understanding.

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

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

The description covers the core functionality and prerequisite, leaving parameter details to the schema. Since there is no output schema, return values are not explained, but for a creation tool this is acceptable. It lacks guidance on discovering node IDs or pillar names, but siblings like browse_topics exist for that purpose, so the description is sufficient for basic use.

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 meaningful descriptions for all six parameters. The description adds limited extra meaning, mapping 'specific rules' to nodes and 'email or webhook' to channels, but does not elaborate on the channels object structure or the webhook_url dependency. The schema already handles these details, so baseline 3 is appropriate.

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

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

The description clearly states the tool subscribes to regulatory change alerts, watching specific rules (nodes) or pillars, and notifies via email or webhook on primary source changes. It distinguishes itself from siblings like get_latest_changes by focusing on creating a continuous subscription rather than fetching current changes.

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 use case: create an alert subscription for ongoing change notifications. It mentions a critical prerequisite (active Bidda subscription with api_key) but does not explicitly compare with alternatives such as get_latest_changes or browse_topics, nor state when not to use this tool.

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