lbb_fit_sources

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

With only readOnlyHint=true in annotations, the description carries the behavioral load and does well: preview 'calls no model and stores nothing', and list exposes spend, budget, lag, error state and per-status suggestion counts. The pipeline sentence (reads every instance, proposes changes, files suggestions) describes fit-source processing generally and could momentarily be read as this tool's own effect, a small ambiguity.

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?

Information is front-loaded and dense, but the long opening sentences bundle background about the fit-source pipeline that is more relevant to lbb_fit_sources_manage than to a read-only viewer. The parenthetical enumerations are useful but make it run long for a list/get/preview tool.

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

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

There is no output schema, so the description's enumeration of what list and get return (progress, lag, instances read, proposals kept/dropped, spend, budget, last error) is necessary and supplied. For a 10-parameter tool at 80% schema coverage, this is close to complete, with only minor gaps around sample/detail behavior.

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 80%, and the description still adds meaning by mapping each action to its inputs and outputs (e.g. preview takes fields/instances, get takes a name). The from/exclude/context params are only summarized implicitly, but the action-driven semantics are clarified 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 identifies the resource (fit sources declared on classes) and scopes the tool to read-only views via the list/get/preview actions, and it names the sibling that handles writes (lbb_fit_sources_manage). The opening 'Fit from text, read only' is jargon-heavy and slightly indirect about the verb, which keeps it below 5.

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

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

It explicitly allocates the three supported actions (list shows all, get shows one, preview shows fields/samples) and routes declare/refresh/dry-run to lbb_fit_sources_manage and suggestion inspection to lbb_inspect action=ontology_suggestions. When-to-use and where-not-to-go are fully stated.

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