{
  "access": "public",
  "type": "reference",
  "format": "markdown",
  "title": "Flux Tools Reference",
  "chunked": true,
  "url": "https://library.datagrout.ai/flux-tools",
  "summary": "Capture feedback and quality signals around agent output.",
  "content_markdown": "# Flux Tools\n\nCapture feedback and quality signals around agent output.\n\nFlux is the review and measurement surface for DataGrout. Use it to collect qualitative feedback, rate specific tools used in a session, and track custom events tied to user journeys or workflow outcomes.\n\n---\n\n## `flux.feedback@1`\n\nSubmit platform or workflow feedback.\n\nCall with no arguments to receive a guided feedback prompt, or pass feedback fields directly to store a structured submission.\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `nps_score` | integer (1-10) | no | Overall experience rating |\n| `liked` | string | no | What worked well |\n| `improve` | string | no | What should improve |\n| `highlight` | string | no | Specific tool or experience to call out |\n| `free_text` | string | no | Open-ended feedback |\n| `ease_of_use` | integer (1-5) | no | How intuitive the tools were |\n| `trust_level` | integer (1-5) | no | How much you trusted the outputs |\n| `surprise_score` | integer (1-5) | no | How much the tools surprised you |\n| `would_use_voluntarily` | boolean | no | Would you reach for these tools by choice? |\n| `unique_capability` | string | no | What this system can do that you can't do natively |\n| `feedback_ref` | string | no | Reference to a prior submission for follow-up feedback |\n| `agent_name` | string | no | Name of the client or agent submitting feedback |\n| `model` | string | no | Model used during the session |\n| `ref` | string | no | Reference to a specific tool call or cache_ref |\n| `campaign_id` | integer | no | Campaign ID if responding to a Flux campaign |\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/flux.feedback@1\",\n  \"arguments\": {\n    \"nps_score\": 8,\n    \"liked\": \"Discovery found the right tools quickly\",\n    \"improve\": \"Tool descriptions could be shorter\",\n    \"agent_name\": \"Cursor\",\n    \"model\": \"gpt-5\"\n  }\n}\n```\n\n---\n\n## `flux.scorecard@1`\n\nRate the individual tools used during a session.\n\nScorecard is useful after a workflow or experiment when you want per-tool ratings instead of only a single overall impression.\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `feedback_ref` | string | no | Link the scorecard to a prior feedback submission |\n| `tools` | array | yes | List of rated tools |\n\nEach entry in `tools` includes:\n\n- `tool`\n- `rating`\n- optional `comment`\n- optional `would_use_again`\n- optional `bugs`\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/flux.scorecard@1\",\n  \"arguments\": {\n    \"feedback_ref\": \"fb_abc123\",\n    \"tools\": [\n      {\n        \"tool\": \"discovery.perform\",\n        \"rating\": 5,\n        \"comment\": \"Very easy to use\"\n      },\n      {\n        \"tool\": \"prism.refract\",\n        \"rating\": 4,\n        \"comment\": \"Good results after payload cleanup\"\n      }\n    ]\n  }\n}\n```\n\n---\n\n## `flux.track@1`\n\nTrack a custom event tied to usage or workflow state.\n\nUse this when you want structured product or operational events alongside qualitative feedback.\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `event_name` | string | yes | Name of the event |\n| `event_data` | object | no | Arbitrary structured event payload |\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/flux.track@1\",\n  \"arguments\": {\n    \"event_name\": \"skill_invoked\",\n    \"event_data\": {\n      \"skill_id\": \"skill_abc123\",\n      \"surface\": \"toolsmith.invoke\"\n    }\n  }\n}\n```\n\n---\n\n## When To Use Flux\n\n| Scenario | Tool |\n|----------|------|\n| Capture overall qualitative feedback | `flux.feedback` |\n| Rate specific tools used in a session | `flux.scorecard` |\n| Record custom product or workflow events | `flux.track` |\n"
}