lbb_fit_sources_manage

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

Annotations only say readOnlyHint=false, openWorldHint=false, destructiveHint=false; the description adds substantial context beyond that – dry_run spends model budget but files nothing, declare files suggestions and only alters what you name, refresh is fire-and-return with the job also auto-running after each published commit, and nothing reaches the ontology until a human accepts. This is exactly the kind of side-effect and cost disclosure the annotations cannot convey.

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 workflow prerequisite is front-loaded and each sentence carries real information (action semantics, cost, polling, safety). It is dense and on the long side for one paragraph, but there is essentially no filler to cut.

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 multi-action mutation tool with no output schema, the description covers everything an agent needs: prerequisites, the return shape of dry_run (proposals with quote, support score, checks), background/polling behavior, and the human-acceptance gate. Nothing material 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 description coverage is 88% (baseline 3), but the description earns extra credit by explaining the semantics of the three action values, which the schema's enum leaves entirely undocumented. It also clarifies declare's modify-only-what-you-name behavior and dry_run's truncation/60s scope, though it adds little on from/context/exclude beyond the schema text.

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 the specific resource (a fit source, i.e. fit-from-text) and enumerates the three concrete verbs it supports (declare, dry_run, refresh), each with a distinct function. It also distinguishes itself from the sibling lbb_fit_sources by pointing to its preview and get actions, so an agent can route correctly without opening any schema.

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 an explicit prerequisite/workflow ordering ("Run lbb_fit_sources action=preview first and show the user the text") and names the sibling actions used for previewing and polling progress. It clearly implies which action to pick (dry_run to trial cheaply, declare to persist, refresh to force a run), though it never states an explicit when-not-to-use case.

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