Bidda Sovereign Intelligence

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

The description adds behavioral details beyond the readOnlyHint and openWorldHint annotations, such as returning aggregated counts and supporting drill-in via the topic parameter. It explains the conceptual relationship to pillars, which is useful. The mention 'Free, no key required' is redundant with openWorldHint, but the rest adds value.

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 well-structured and front-loaded with the core purpose. It contains five sentences, but one sentence ('Free, no key required') duplicates the openWorldHint annotation and could be removed without loss. Overall, the description is efficient and informative.

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

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

For a simple read-only tool with one optional parameter, the description covers the essential aspects: what it does, what it returns, and the parameter's effect. It also provides context on how topics relate to pillars. Since there is no output schema, the description's mention of 'how many rules carry it and across how many pillars and jurisdictions' helps set expectations, though it could mention edge cases like no results.

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

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

The schema already describes the topic parameter as 'Optional topic name to filter or drill into,' and the description reinforces this with 'Pass a topic string to drill into one.' It also clarifies the default behavior by stating the tool returns all topics when no parameter is passed. The examples of topics add semantic richness beyond the schema.

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

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

The description clearly states the tool's function: 'Browse the registry by cross-cutting compliance TOPIC' and specifies the output—'each topic with how many rules carry it and across how many pillars and jurisdictions.' It distinguishes itself from siblings like list_pillars by emphasizing that topics are cross-cutting and sit on top of the 39 pillars without replacing them.

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 the tool: for browsing topics rather than pillars or other registry views. It also explains the optional topic parameter, saying 'Pass a topic string to drill into one.' However, it does not explicitly mention alternatives or when not to use it, so it stops short of full explicit 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 provide readOnlyHint=true and openWorldHint=true. The description adds value by detailing the output (ranked list of regulations, risk indicator) and the 'may apply' nuance, indicating a non-exhaustive heuristic. This aligns with annotations and adds transparency.

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

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

Two sentences, front-loaded with the core purpose, then examples, then positioning. No redundant 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?

The tool has 3 params, no output schema. The description provides sufficient context about inputs (natural language action), outputs (ranked list + risk indicator), and usage domain. It could detail the output structure more, but for a read-only compliance check, this is adequate.

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

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

The schema covers 100% of parameters with descriptions. The description enhances the 'action' parameter with concrete examples (EU biometric data, health records transfer, trading model) that teach the agent how to phrase queries. Limit and jurisdiction are already well-documented in schema.

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

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

The description clearly states the tool's function: a pre-flight regulatory check that takes natural-language action descriptions and returns ranked regulations with a risk indicator. It distinguishes itself from siblings by being 'the primary tool for runtime compliance gating'.

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

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

It explicitly frames when to use: before performing an action, as a pre-flight check, and positions itself as the primary tool for runtime compliance gating in autonomous workflows. It doesn't explicitly name alternatives or when-not-to-use cases, but the context is strong.

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 is not required to restate safety. It adds valuable behavior: it 'surfaces the real rules and numbers' rather than opinions, explicitly does not rank, and discloses the subscription requirement ('Requires an active Bidda subscription') and how to pass the key (api_key). This goes beyond the schema by framing the tool's output philosophy and access prerequisite, though it does not detail error handling or return format.

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

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

The description is 60 words across three sentences, each earning its place: the first defines the core purpose and an illustrative example, the second clarifies the non-ranking behavior and focus on real data, and the third covers authentication requirements. It is front-loaded with the most important information and contains no redundant 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 only two params and no output schema, the description gives adequate context for correct invocation: what topic to provide, what the tool does, what it does not do, and the required authentication. The main gap is the lack of any description of the response format; while 'surfaces the real rules and numbers' hints at the content, an agent might benefit from knowing whether results are returned as a table, list, or structured document. With no output schema, a short note on return structure would complete the picture. Still, this is a minor omission given the strong clarifying statements elsewhere.

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

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

Schema description coverage is 100% and both parameters are described: topic includes an example, and api_key has a thorough explanation of header vs argument precedence and free trial inclusion. The description does not add significant new parameter-level meaning beyond what the schema already provides; it only corroborates the api_key need. Baseline 3 is appropriate because the schema fully documents parameters.

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

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

The description opens with a clear verb and resource: 'Compare how different jurisdictions address a compliance topic, side by side.' It specifies the scope (jurisdictions, compliance topics) and the distinctive behavior of surfacing numeric thresholds (e.g., 72 hours vs 30 days). This distinguishes it from sibling tools like get_jurisdiction_bundle or check_action_compliance, and it states explicitly that it does not rank jurisdictions, removing ambiguity about its output philosophy.

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 defines when to use the tool: when a side-by-side comparison of jurisdictions' rules on a compliance topic is needed. It also implies a contrast with ranking tools by stating 'does not rank which jurisdiction is stricter.' However, it does not explicitly name alternative tools for different use cases (e.g., single-jurisdiction lookup or compliance checking), nor does it state conditions when not to use this tool. It gives clear context but lacks explicit exclusionary 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?

The description adds meaningful behavioral context beyond the annotations: it consumes one call on the key, records an entry, pins the node to its version and integrity hash, and requires an active Bidda subscription. This gives the agent a clear picture of side effects and proof semantics 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?

The description is compact, front-loaded with the main purpose, and every sentence earns its place: it explains the combined operation, the integrity-pinning behavior, when to use it instead of get_node, and the auth requirement. No unnecessary filler is present.

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 operation, side effects, prerequisites, and usage context, which is strong given the tool's complexity. The only minor gap is that with no output schema, an explicit statement of the return shape would have been slightly more complete, but the description already implies the node is fetched and the entry recorded.

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 detailed description, so the baseline is 3. The tool description reinforces the role of run_id and node_id and mentions api_key, but it does not add substantive parameter-level meaning beyond what the schema already provides.

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

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

The description clearly states a specific composite action: fetch the full vault node and record a verified node_consulted entry in one call. It also distinguishes itself from get_node by explicitly naming the sibling and the condition for choosing this tool, so an agent can tell them apart immediately.

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 instead of get_node when you are inside a run,' which is a direct when-to-use instruction with a named alternative. It also states the prerequisite of an active Bidda subscription and that recording happens on an open run, giving the agent the conditions needed to invoke it 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 mark readOnlyHint=false and destructiveHint=false, so the write nature is covered. The description adds meaningful context: the subscription requirement, the public verify URL, and the implication of immutability ('confirm the record has not been changed'). 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 compact—four short sentences, each with a distinct purpose: what it creates, what it returns, typical use, and a prerequisite. It is front-loaded with the core action and avoids filler. Slightly longer than two sentences but still efficient.

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

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

For a tool with 5 parameters, no output schema, and moderate complexity, the description covers the core outcome (returned record ID and verify URL), the prerequisite (subscription), and the general use case. It omits edge cases, error behavior, and the sibling differentiation, but those are not critical for basic invocation. It is sufficiently complete for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add any detail about agent or nodes beyond what the schema provides. It only mentions api_key in the context of subscription, which is already elaborated in the schema parameter description (including header precedence). Thus, it adds minimal extra semantic value.

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

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

The description states a clear verb-resource pair: 'create a signed, time-stamped record of which Bidda rules...'. It also explains what is returned (record ID and verify URL). However, it does not explicitly distinguish this from the sibling create_control_attestation, leaving the agent to infer the difference from the name alone.

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

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

It gives a clear use case ('useful for agents that must keep an audit trail') and mentions a prerequisite (Bidda subscription). But it offers no explicit comparison to alternatives, nor any 'when not to use' guidance. The sibling create_control_attestation is never referenced, so selection between them is left implicit.

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

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

Annotations already declare write, non-idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it pins obligations to their version and integrity hash at signing time, and clarifies the subscription requirement and header precedence for api_key. This enriches the agent's understanding of side effects and dependencies.

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 compact paragraphs that front-load the purpose and distinguish the tool from run receipts. It includes the key behavioral note (pinning) and a practical usage hint (api_key header). It is efficient, with minimal fluff, though a slight trim could make it even tighter.

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 9 parameters and no output schema, the description covers the core purpose, the mapping behavior, the evidence type, and a prerequisite. It does not detail return values (no output schema expected) but provides enough for an agent to decide when to call and what to provide. Minor gaps such as error handling are not essential here.

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 every parameter, including api_key header precedence. The description does not add new semantic details about parameters beyond what the schema provides; it only reiterates the subscription requirement. Baseline 3 is appropriate when the schema fully covers parameter meaning.

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

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

The description begins with a specific verb 'Sign' and a clear resource: 'tamper-evident record of one of YOUR OWN controls or policies and the Bidda obligation nodes it maps to.' It also contrasts with 'run receipts' to clarify the design-side evidence role, effectively differentiating from other attestation-like 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?

It states when to use this tool: 'design-side evidence' vs 'running-side evidence' from run receipts, giving a clear context. It also states a prerequisite ('Requires an active Bidda subscription: pass api_key'). It does not explicitly name an alternative sibling tool, but the run-receipt contrast conveys appropriate usage.

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 and openWorldHint, which the description does not contradict; it adds behavioral context by explaining what 'drift' and 'withdrawn' mean and that the response is per-rule status. It also notes batch-size scaling with plan tier, going beyond the annotations without conflicting with 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 well-structured with a clear frontal statement of purpose, followed by input/output detail and behavioral context. The final sentences about tier inclusion and 'Pass api_key' are slightly redundant given the schema, but they do not bloat the text significantly. Overall, every sentence 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?

For a tool with two parameters and no output schema, the description covers what the agent receives (per-rule status) and how to act on it. It does not specify an exact response format, but that is not essential for call selection. The description is sufficient for correct invocation and interpretation without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic value: it explains the purpose of the hash (integrity check against last grounding), the node_id context (rules), and clarifies that api_key is optional and that the header takes precedence. This provides meaning beyond the schema's 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 opens with a specific verb ('Check') and a precise resource ('compliance rules an agent has cached'), clearly distinguishing it from sibling tools like get_latest_changes or watch_changes. It also enumerates the three possible outcomes (fresh, drifted, withdrawn), making the tool's 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 explains when to use the tool ('before acting on stale law') and how to prepare inputs (submit node_id and stored hash). It does not explicitly name alternative tools or state when not to use it, but the context is clear and there are no misleading 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 declare readOnlyHint=true, and the description adds the subscription requirement, the dependency-graph mechanism, and explicitly notes it does not rank compliance. It does not contradict annotations and supplies context beyond the structured metadata.

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 paragraph with two efficient sentences. The core function is front-loaded, and the 'coverage aid' phrasing with a dash adds a bit of fluff but does not waste space. It is concise and readable.

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

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

With no output schema, the description does explain the high-level output (gaps and withdrawn rules). It states the auth requirement and what the tool does not do. For a read-only tool with well-documented params, this is sufficiently complete, though return structure detail is absent.

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

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

Schema description coverage is 100%, with each parameter (depth, nodes, api_key) already explained. The description adds no deeper meaning about parameter syntax or relationships; it only mentions passing api_key, which the schema already covers. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('return') with a clear resource (prerequisite rules from the dependency graph) and explicitly defines the two outputs: missed prerequisite gaps and withdrawn covered rules. It also distinguishes itself from ranking/determining compliance, separating it from other review 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 frames the tool as 'a coverage aid for a qualified reviewer' and states it does not rank or determine compliance, giving some context. However, it does not name specific sibling tools or provide explicit when-to-use versus when-not-to-use guidance, leaving inference to the agent.

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 the important behavioral trait that a still-open run's draft pack requires api_key, and clarifies that sealed runs are readable by id. 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?

Two sentences; the first lists contents compactly, the second clarifies state-dependent behavior. No redundant or filler text; every phrase adds 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 2-parameter tool with no output schema, the description sufficiently describes what the tool returns (pack contents) and the access conditions. No missing critical information such as error cases, but those are not necessary for a read-only export.

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 already documents both parameters with 100% coverage. The description adds the conditional that api_key is needed for unsealed runs, which clarifies the otherwise optional parameter's role. This extra context elevates it above the baseline.

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

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

The description clearly states the tool exports a run as a governance evidence pack, listing concrete contents (signed receipt, entries, node roll-up, hash-chain/Merkle check, coversheet). This distinguishes it from sibling tools like get_run by specifying the full audit pack rather than just run details.

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 about sealed vs open runs and the api_key requirement, but does not explicitly mention when to use this tool over alternative siblings (e.g., get_run). No exclusions or alternative tool references are given, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context by noting that discovery returns available dimensions while full mapping values are vault-gated, which tells the agent about a two-tier access model not captured 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 with front-loaded action, includes a clarifying example, and ends with a concise note on access levels. Every sentence earns its place 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?

Given the simple schema (one parameter) and lack of output schema, the description adequately covers the return value ('mapping dimensions') with an example and notes the vault-gating nuance. It is complete enough for a look-up tool, though a brief mention of output format would have made it fully concrete.

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 100% coverage with a clear description of node_id ('Node ID to inspect crosswalks for'). The description's mention of 'for a node' adds no significant semantic detail beyond the schema, so the baseline score 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+resource ('Return the cross-framework mapping dimensions for a node') and includes a concrete example chain. It distinguishes itself from siblings like get_mitre_mapping by focusing on cross-framework mappings across regulations, standards, and jurisdictions.

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 its use case when cross-framework mappings are needed, but it does not explicitly state when to use this tool versus alternatives. It lacks exclusions or direct comparisons with sibling tools such as get_mitre_mapping or compare_jurisdictions, so guidance is only implied.

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

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

Annotations already signal read-only and open-world hints, lowering the bar. The description adds useful behavioral details beyond the schema: it explains the tool's traversal behavior (full dependency tree), gives a typical size estimate (3-8 upstream nodes), and clarifies the default depth (2) and maximum (4). 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 three sentences, front-loaded with the action, followed by a clear explanation, use case, and parameter defaults. Every sentence contributes meaning without 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?

The tool is relatively simple with two parameters and no output schema. The description covers what the tool does, when to use it, and its key behavioral constraints. It doesn't detail the exact structure of the returned tree, but given the tool's straightforward nature and the presence of the input schema, it is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the default/max depth information already present in the schema ('Defaults to depth 2; max 4') but doesn't add substantial new meaning beyond what the schema provides. The phrase 'full dependency tree' gives some context but is not parameter-specific.

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 walks the prerequisite chain for a compliance node and returns the full dependency tree, which distinguishes it from sibling tools like get_node (single node retrieval) and search_nodes (search). It uses a specific verb+resource construction and explains the output at a high level.

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 usage context: 'Use this to plan a complete compliance posture' and notes that unlocking one node typically requires understanding 3-8 upstream nodes. It doesn't explicitly name alternatives or when not to use it, but the context is clear enough for an agent to decide.

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 read-only safety, so the description need not repeat that. It adds useful context about the jurisdictions covered and the 'full regulatory surface' concept, but doesn't disclose behavior like pagination or result ordering. With annotations providing the safety profile, this is adequate but not rich.

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

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

Two sentences, front-loaded with the action and resource, with no filler. The first sentence states the core function, and the second gives a concrete use case. 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 simple filtered-list tool with two parameters and no output schema, the description covers the essential context: what it returns, which jurisdictions are supported, and when to use it. It could mention response format, but the readOnlyHint and openWorldHint supply additional context, making it sufficiently 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 description adds no significant meaning beyond what parameters already document. The jurisdiction list is duplicated from the schema, and 'limit' is fully described in the schema. Baseline score of 3 is appropriate because the schema does the heavy lifting.

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

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

The description uses a specific verb ('Return all compliance nodes that apply') and clearly identifies the resource (compliance nodes for a jurisdiction). It distinguishes itself from siblings like compare_jurisdictions by focusing on a single jurisdiction's full regulatory surface, making the tool's unique purpose obvious.

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

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

Explicitly states when to use: 'when an agent enters a new market and needs the full regulatory surface for that geography.' This provides clear context and implies an exclusion for comparative or topical needs, though it does not explicitly name alternative 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?

Annotations already mark the tool as readOnly and openWorld. The description adds context about it being a regulatory change feed and provides scheduling advice, but does not disclose return format, pagination, or other behavioral details. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is three sentences, front-loaded with the primary purpose. Every sentence adds value: purpose, usage, and scheduling guidance. There is no fluff or redundancy.

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

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

For a simple read-only tool with two optional parameters and no output schema, the description covers the core purpose, use case, and operational guidance. It doesn't detail return values, but the description implies the result is a list of nodes, which is sufficient for this complexity level.

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 parameters described in the schema. The description adds minimal extra meaning ('Filter by pillar to focus on a domain'), essentially paraphrasing the schema. This matches the baseline 3 for high schema coverage.

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

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

The description clearly states the tool lists recently updated compliance nodes, framing it as the regulatory change feed. It uses specific verbs ('List', 'monitor') and resource scope, and differentiates from siblings by emphasizing its role as a feed for monitoring amendments and new guidance.

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 to use this tool for monitoring incoming changes and suggests calling it on a schedule to keep compliance posture current. It also mentions filtering by pillar, giving concrete usage context. However, it does not explicitly mention alternatives or when not to use it, 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that it returns a Bidda node plus obligations and mentions 'Free', but does not detail rate limits, authentication, or response structure beyond that.

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 a memorable metaphor and then detailed specifics. It is slightly verbose with 'The MITRE Rosetta Stone' and 'Free', but each part adds flavor or info. No wasted sentences.

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 complexity (multiple frameworks and compliance standards) and no output schema, the description should explain more about the response format. It lists the standards but not the structure, which is a notable gap for an AI agent.

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

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

The schema description covers 100% of the parameter with extensive valid ID examples. The tool description adds framework context but introduces a slight inconsistency by listing 5 frameworks while schema includes CAPEC as an additional valid input type. Overall, the schema does the heavy lifting.

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

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

The description clearly states the tool maps a MITRE technique ID to a Bidda node and associated compliance obligations across multiple frameworks. It distinguishes itself from siblings by its specific 'Rosetta Stone' role, bridging SOC and compliance terminology.

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

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

Usage is implied clearly: when you have a MITRE technique ID and need mapping to compliance controls. It does not explicitly name alternatives or say when not to use, but the context is strong enough to guide selection among sibling 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?

The description adds useful context beyond annotations: it specifies that the tool returns a summary (title, compliance pillar, version, last updated, BLUF) and that the full node is accessible at bidda.com. While readOnlyHint and openWorldHint already indicate safety and open nature, the description clarifies the output content and external reference, enhancing behavioral transparency.

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

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

The description is concise and well-structured. It opens with the key action, then enumerates the summary fields, and finally points to the full node location. Every sentence provides value with no redundancy or extraneous details.

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

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

For a simple get-by-ID tool with one parameter and no output schema, the description covers the return summary and directs users for full details. It does not mention error handling or when a node might not be found, but given the tool's simplicity and annotations, it is sufficiently complete.

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

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

Schema coverage is 100%, with the 'id' parameter fully described including examples. The tool description adds little beyond the schema, only confirming that the ID refers to a node. Since the schema handles parameter semantics, a 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 'Get a specific compliance node by its ID' with a specific verb and resource. It distinguishes from sibling tools like search_nodes by emphasizing 'specific node' and 'by ID', making the purpose unambiguous.

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

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

The context is implied: use this when you have a node ID and want a summary. However, no explicit alternatives or exclusions are provided, such as directing users to search_nodes for finding IDs or browse_topics for exploration. The 'by its ID' gives some hint but lacks explicit comparison.

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 indicate readOnlyHint and openWorldHint, but the description goes beyond by disclosing that sealed runs are publicly readable by id and that the tool reports signature validity. This adds important behavioral context regarding access control and output details, which is valuable beyond the structured 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 main action and includes necessary access and behavior details. Every sentence contributes to understanding the tool's purpose and usage without 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?

Given no output schema, the description tells the agent what to expect (run and entries) and even mentions signature validity reporting, which is a key part of the return. It doesn't elaborate on structure or error cases, but for a simple fetch operation with two parameters, this is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning to the api_key parameter by explaining it's needed for owners to read open/sealed runs, while sealed runs are publicly readable without it. This clarifies the practical use of the parameter beyond the schema's simple 'required to read your own still-open run' description.

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

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

The description clearly states the tool's purpose: 'Fetch a run and its entries.' This uses a specific verb (fetch) and resource (run with entries), and distinguishes it from sibling tools like open_run and seal_run which are lifecycle operations. The additional detail about open/sealed runs and ownership further clarifies the scope.

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

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

The description gives clear context on when to use the tool and how to handle api_key for open vs sealed runs. It doesn't explicitly name alternatives or when not to use it, but the ownership and public/private distinctions provide enough guidance for an agent to decide 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. Beyond that, the description adds useful context by listing what the tool returns: counts, 10,099 nodes, 39 pillars, and specific frameworks. This gives the agent a concrete sense of the registry's breadth without confusing role details.

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

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

The description is two sentences and immediately front-loads the core action: 'List all compliance pillars...'. The second sentence provides useful registry context and examples without unnecessary 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?

For a zero-parameter list tool with no output schema, the description explains the return content, typical placement in a workflow, and the authoritative scope of the registry. It is sufficiently complete for an agent to select and invoke.

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

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

The tool takes zero parameters, so the baseline is 4. The input schema fully captures this (required: [], properties: {}), so no parameter documentation is needed. The description focuses on the output semantics instead.

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 a specific verb and resource: 'List all compliance pillars in the Bidda Sovereign Intelligence registry with node counts.' It clarifies the exact output and ties the tool to an initial discovery role, distinguishing it from search-oriented tools like 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 explicitly instructs when to use it: 'Use this first to discover available compliance domains before searching.' This gives a clear usage context, though it does not explicitly name alternative tools 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 declare readOnlyHint=true and openWorldHint=true, and the description does not contradict them. The description adds genuine behavioral context beyond the annotations: the subscription/auth requirement ('Requires an active Bidda subscription: pass api_key') and the edge-case semantics of what counts as a delta ('or whose node was withdrawn'). It omits rate limits and response format, but those are secondary for a read-only feed.

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 with zero waste: definition, canonical use case, and operational requirement. The core resource semantics are front-loaded before the usage hint, making the tool's identity clear in the first line.

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

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

No output schema exists, so the description carries the burden of conveying what comes back; the first sentence does sketch the output content (source refs mapped to affected obligation nodes). Gaps remain: result ordering, how limit interacts with pagination, and the field structure of a delta item. For a simple read-only feed with fully documented parameters this is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value on top by grouping three params into their functional role ('filterable by time, pillar, or specific nodes'). It also flags api_key as effectively required ('Requires an active Bidda subscription: pass api_key') even though the schema declares it optional, which is a useful cross-reference with the header-precedence note.

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?

Names a specific resource ('the obligation-level change feed'), a concrete transformation ('primary sources whose content changed... mapped to the Bidda obligation nodes they affect'), and explicit filter scope ('time, pillar, or specific nodes'). The 'obligation-level' qualifier differentiates it from sibling change feeds like get_latest_changes and watch_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?

Provides an explicit usage directive: 'Use it to answer "what obligations changed since I last reviewed?"', which clearly frames when this tool is the right choice. However, it never names sibling alternatives (e.g., get_latest_changes or watch_changes) or states when NOT to use it, so contrastive guidance is left to inference.

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

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

Annotations already cover read/write and idempotency, and the description adds behavioral context beyond that: the ledger is signed and tamper-evident, returns a run_id, and requires an active Bidda subscription via api_key. This is consistent with the annotations, which mark the operation as non-read-only and non-destructive.

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 tool's core function, then return value, workflow, and requirement. Every sentence carries useful information without 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 create-style tool with three params, the description explains the purpose, return value, workflow continuation (record_run_entry, seal_run), and auth requirement. No output schema exists, so noting run_id is sufficient; nothing critical is missing.

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

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

Schema covers all three parameters with descriptions (100% coverage), including header precedence for api_key. The description adds only a redundant subscription requirement reference, so it doesn't significantly expand on the schema.

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

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

States a specific verb and resource ('Open a run ledger') and explains the return value (run_id). It clearly differentiates from siblings by outlining the workflow with record_run_entry and seal_run, so an agent can tell it starts a new ledger rather than reading or appending.

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 start a run ledger for a task/conversation, then use record_run_entry per turn and seal_run to finish. It does not explicitly name alternatives like get_run or state when not to use it, but the workflow makes the intended usage evident.

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?

Adds value beyond annotations by disclosing the api_key requirement for open runs and the document's internal structure. readOnlyHint is consistent with 'Export'. No contradictions. It doesn't mention response format, but the description compensates with run-state specifics.

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 fluff. The first sentence is information-dense but coherent; the second clarifies the api_key condition. Every phrase 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 tool has no output schema, so the description appropriately explains what the OSCAL document will contain (reviewed-controls, observations, props). It also addresses run state, which is key for usage. Missing minor details like exact serialization format, but overall complete for a straightforward 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 already covers both parameters well (100% coverage), so baseline is 3. The description adds meaning by explaining that api_key is needed specifically for open runs, and that run_id refers to the run to export. This is a meaningful addition over the schema 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 the verb 'Export' and resource: 'a governed run's evidence as a NIST OSCAL assessment-results document'. It also enumerates specific content items (reviewed-controls, observations, props), making it distinct from sibling tools like get_run or 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 context: this is for exporting to OSCAL for GRC/audit tooling. It gives a usage condition ('A sealed run is readable by id; a still-open run needs your api_key') but does not explicitly name alternative tools or say when not to use it. The context is sufficient for most use cases.

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 valuable context beyond the annotations: the call requires a Bidda subscription, the record is signed, and it is anchored to the public history chain. It is slightly ambiguous whether this is purely a read of an existing record or creates a new signed record, especially given readOnlyHint=false and the title 'Sign a point-in-time record', but the description is reasonably transparent overall.

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 no filler: core purpose, use case, and prerequisite. The most important semantics are front-loaded, and 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?

There is no output schema, but the description explains the high-level output: a signed record of which committed version was authoritative. It omits exact response fields and failure behavior, but for a three-parameter tool with complete schema coverage and clear auth guidance, this is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces that api_key is needed and that as_of relates to a past date, but it does not add meaningful detail beyond what the input schema already provides.

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

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

The description names a specific operation ('Get a signed record') and a precise resource: the committed version of a rule authoritative at a past date, anchored to the public history chain. The use case ('show what a rule said at the moment it acted') clearly distinguishes it from current-state or change-log siblings like get_node and 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?

The description gives a concrete scenario ('when an agent must show what a rule said at the moment it acted') and states the prerequisite of an active Bidda subscription with an api_key. It does not name alternative tools or say when not to use it, but the intended context is clear enough.

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 behavioral traits beyond annotations: each entry is hash-chained (important for integrity), requires an active subscription, and explains the api_key header vs argument precedence. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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

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

Two sentences that front-load the primary action and content, then include critical behavioral details (hash-chaining, auth) without fluff. 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 12-parameter tool with no output schema, the description covers the essential purpose, key constraints (open run, auth), and the distinction between textual and hashed input. No critical information for correct use 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 description adds value beyond the schema by clarifying that the end user's input can be sent as text via note or privately via input_hash, and by explaining that verify_nodes provides proof by pinning nodes to versions. These enrich meaning without repeating schema 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 the action (Append one entry) and the resource (an open run), plus the content (rules consulted, decision, end user input). It is specific and distinct from sibling tools like open_run, get_run, and seal_run, which have different purposes.

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

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

The description implies when to use it (recording a run entry) and mentions prerequisite (active Bidda subscription, api_key). It does not explicitly contrast with sibling tools, but the purpose is clear enough that an agent can infer when to call it.

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

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

Annotations already mark the operation as non-read-only, idempotent, and non-destructive; the description adds useful context by describing the signed receipt, the public verification URL, and the subscription requirement. 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?

Two concise sentences front-load the core action and output, then add idempotency and auth requirements. Every sentence carries meaningful information with no filler.

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

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

For a two-parameter tool with no output schema, the description provides the essential return concept (a signed receipt with public verify URL), idempotency, and auth prerequisite. It does not describe the receipt structure in detail, but that is unlikely to block correct invocation.

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

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

The schema already documents both parameters fully (100% coverage), including the header-precedence behavior for api_key, so the description does not need to add much. Its mention of needing a subscription loosely reinforces api_key's purpose but adds little beyond the schema.

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

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

States a specific verb ('Seal'), the target resource ('an open run'), the output ('one signed Run Receipt covering every entry, with a public verify URL'), and the idempotent behavior. This clearly differentiates it from sibling tools like open_run or record_run_entry without needing to inspect schemas.

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

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

It clearly indicates this is for an open run that should be closed into a receipt, and idempotency covers repeated calls. It names the subscription requirement, but it does not explicitly name alternative tools or say when not to use it, so it stops just short of full guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's mention of return format (summaries with BLUF) and the no-hallucination, source-tracing guarantee adds meaningful behavioral context beyond the structured fields. It does not contradict annotations and provides useful reliability 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 concise: three sentences that front-load the purpose, then describe the return value, and end with concrete examples. Every sentence adds value, with no fluff or redundancy.

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

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

Given that there is no output schema, the description compensates by explaining the return structure (summaries with BLUF) and the source-tracing guarantee. It covers the essential behavioral context for a search tool, including typical query examples. Minor gaps like match semantics or limit/pillar behavior are left to 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 coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema provides, though the example queries illustrate how to phrase the query parameter. This aligns with the baseline expectation.

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

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

The description opens with a specific verb and resource: 'Search Bidda compliance nodes by keyword.' It clearly distinguishes itself from sibling tools like browse_topics or consult_node by focusing on keyword search and output summaries. The BLUF sentence and example queries further clarify 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 context: use this to search nodes by keyword and get concise summaries with source links. However, it does not explicitly state when not to use it or contrast with alternatives like browse_topics or get_node. The examples imply typical use cases, giving adequate but not exhaustive 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 indicate readOnlyHint=false and idempotentHint=false, so the description correctly does not contradict that this is a non-idempotent write operation. It adds context about the Bidda subscription requirement and delivery channels, but does not explain side effects like duplicate alert creation, result format, or whether the subscription is persistent. The description adds some value beyond annotations but is not rich in behavioral disclosure.

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

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

The description is a single, well-structured sentence that front-loads the purpose ('Subscribe to regulatory change alerts') and uses a colon to introduce the requirement. It covers key aspects without fluff, making it easily scannable and 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?

The description explains the trigger (primary source changes), the watch targets (rules/pillars), delivery channels, and the subscription requirement, which covers most operational aspects. However, there is no mention of the tool's return value or output structure, and since there is no output schema, an agent would not know what to expect. For a tool with six parameters and no output schema, this is a notable gap, but it is otherwise 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 all six parameters are already documented. The tool description reiterates the nodes/pillars distinction and email/webhook options, but adds minimal new meaning beyond the schema. Since the schema carries the parameter details, the description 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 clearly states the verb 'Subscribe' and the resource 'regulatory change alerts', specifying that it watches specific rules or whole pillars and notifies via email or webhook. It also includes the prerequisite of an active Bidda subscription, which distinguishes it from sibling tools like get_latest_changes that likely fetch changes rather than create subscriptions. This makes the tool's purpose unambiguous.

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

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

The description provides clear context on when to use the tool: to subscribe to changes, and it notes the subscription requirement. However, it does not explicitly name any alternative tools or state when not to use it, such as directing agents to get_latest_changes for immediate retrieval. The context is present but lacks explicit exclusions.

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