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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered; the description adds genuinely new behavioral context by disclosing that an OAuth connection may be initiated as a side effect before the read. It also discloses what is returned (active business file + authorized tool catalogue). It says nothing about how pagination or search behave, which is the main remaining behavioral gap.

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?

Two short sentences, front-loaded with the action (OAuth connect + return payload) and closed with the call-timing rule. No redundant restatement of the name or title, no filler.

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?

The behavioral and timing story is complete for a discovery tool with no output schema, but with four parameters (three undocumented) the definition leaves the agent guessing about pagination and search semantics. Adequate to call it once, not fully adequate to call it well under result-set constraints.

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 only 25% — business_file_id is documented in the schema, but limit, offset and search carry no descriptions anywhere. The description does not mention any parameter at all, so it fails to compensate for the low coverage, leaving the agent to infer that limit/offset paginate the tool catalogue and that search filters it.

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?

States a specific verb and two concrete resources: it authenticates via OAuth if needed, then returns the active business file ('dossier actif') and the catalogue of authorized tools. The final clause names the sibling call_incwo_tool, so an agent can distinguish this discovery/context tool from the actual tool executor without opening either 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?

Gives two explicit invocation triggers ('après une inscription', 'avant call_incwo_tool') and names the sibling it precedes, which is the key routing decision an agent faces here. No when-not guidance is given, but for a bootstrap/discovery tool the positive triggers are the ones that matter.

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