opencdr_integrations_get

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond that: it does not say what a 'diagnostics' payload contains, what happens if jobs=true and job_id are combined, whether missing IDs error or return empty, or whether results are paginated.

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?

A single front-loaded sentence with no filler, which is structurally good. However, for a three-mode polymorphic tool the terseness becomes under-specification rather than efficiency.

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?

Three optional parameters, no output schema, and three distinct return shapes mean the description needs to explain mode selection and error behavior. It does neither, so an agent cannot reliably invoke this tool correctly on the first attempt.

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 0% for all three parameters, so the description must carry the burden. It hints at the mapping (integration_id → binding, jobs/job_id → diagnostics) but never states precedence, defaults, or that 'parser catalog' apparently requires no parameter at all — leaving the polymorphic selection logic ambiguous.

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 verb 'get' is paired with three distinct resources (parser catalog, integration binding, ingestion job diagnostics), which tells the agent the domain but not how the tool discriminates between them. It is not a tautology, but an agent cannot tell from the description which parameter selects which of the three payloads, so it is only partly distinguishable from siblings like opencdr_settings_get.

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?

No statement of when to use this tool versus the many sibling getters, and no guidance on when each of the three modes applies. The agent has to infer usage entirely from the parameter names.

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