Fetch a run and its entries. The owner can read an open or sealed run (pass api_key); a sealed run is also publicly readable by id and reports whether its signature is valid.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run_id to fetch. | |
| api_key | No | Optional: your Bidda key, required to read your own still-open run. |
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.
Add one secure layer between your agents and this server.
Most tools target distinct functions: discovery, analysis, runs, attestation, and change feeds. However, get_latest_changes, obligation_deltas, and watch_changes all relate to regulatory changes and could be confused, as could get_node vs consult_node. Descriptions clarify, but boundaries are not always obvious.
The majority follow a verb_noun pattern (browse_topics, create_attestation, get_node), but there are deviations like drift_check, gap_check, obligation_deltas, oscal_assessment_results, and point_in_time, which break the convention. Mixed patterns make the API less predictable.
With 25 tools, the server is at the heavy end of the borderline range. Some tools (e.g., get_latest_changes vs obligation_deltas, get_run vs get_audit_pack) have overlapping functionality that could be consolidated, though the broad compliance domain justifies a larger surface.
The server covers discovery, analysis, run ledgers, attestation, and exports, but lacks a standalone way to access full node content outside a run (get_node returns only summaries; full nodes are external). This is a notable gap for compliance work. Also, there's no list of jurisdictions or verification tool for attestations, though these may be outside the server's intent.