Learn candidate validation rules and structural document types from a batch of your records, deterministically - no Blueprint required. Promote results with approve_rule. Source data is not stored.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | Yes | GeodesicAI API key (gai_...) | |
| blueprint | No | Blueprint name (workflow_name) to use | default |
| documents | Yes | List of structured records (objects) to analyze |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the all-false annotations: it is deterministic, requires no Blueprint, and explicitly states 'Source data is not stored.' This provides privacy and operational guarantees that annotations don't convey. However, it doesn't mention side effects or whether any state persists.
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 well-structured sentences. The first sentence front-loads the purpose and key constraints (deterministic, no Blueprint), and the second adds the workflow (approve_rule) and data privacy. No waste 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 no output schema, the description communicates the expected result ('candidate validation rules and structural document types') and adds critical context like determinism, data retention, and the next step. It could explicitly mention return format, but it is reasonably complete for a discovery 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 description coverage is 100%, so the baseline is 3. The description adds minor value by clarifying that blueprint is optional ('no Blueprint required') despite the schema's default, and by equating 'documents' to 'records.' No additional parameter details 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 states the tool learns candidate validation rules and structural document types from a batch of records. It uses a specific verb ('learn') with explicit resource and differentiates itself by noting 'no Blueprint required' and referencing approve_rule as a follow-up, distinguishing 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 intended use is implied through the purpose ('Learn candidate validation rules...'), but there is no explicit when-to-use or exclusions. It mentions 'Promote results with approve_rule' as a workflow hint, but doesn't clarify when to choose this over alternatives like validate or structural_types.
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 have distinct purposes, but several pairs overlap heavily (validate vs validate_repair, repair vs repair_path, analyze_anomaly vs check_drift vs decompose_failure). Detailed descriptions help disambiguate, but the large number of analytics and diagnostics tools creates real selection risk.
The vast majority use a consistent snake_case verb_noun pattern (create_blueprint, list_api_keys, verify_certificate). A few single-word or noun-phrase exceptions (validate, forecast, structural_types, recent_inference_decisions) are minor deviations, but overall the pattern is predictable.
At 37 tools, this exceeds the 25+ threshold for 'too many'. While the governance domain is broad, the set could be consolidated (e.g., merging validate_repair into validate, folding repair_path into repair, or trimming diagnostics-tier tools like check_realization and geometric_confidence).
The surface covers the full blueprint lifecycle, validation, repair, API key management, discovery, inference governance, and chain management. Minor gaps exist: no direct get_blueprint (only list with counts), and chain lifecycle lacks delete/list/cancel operations. Overall, agents can accomplish core governance tasks without dead ends.
