Atisbo

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context: it is a 'broad analytical query' that returns a 'ready-to-render chart artifact,' implying aggregation and visual output. It does not discuss pagination or clamping, but those are disclosed in parameter descriptions, and the annotation bar is lower.

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 sentences carry the full purpose, features, and sibling routing. The core purpose is front-loaded, and the alternative is given without unnecessary elaboration. Zero 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?

Despite 10 parameters and nested objects, the full schema plus output schema covers the necessary details; the description supplies the high-level mental model and routing. It could have given a concrete example query or noted the read-only nature, but annotations and rich schema make the environment complete enough to call correctly.

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 100%, and each parameter already has rich documentation (aliases, clamps, pagination source, provenance warnings, enum semantics). The main description adds no parameter-level detail, so the baseline of 3 is appropriate.

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 states a specific verb ('query') over concrete resources ('claims, solutions, or activity') and lists key capabilities (time filters, grouping, metrics, chart artifact). It explicitly distinguishes itself from atisbo_lookup by naming it and the drill-down use case, so an agent can separate them without inspecting schemas.

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?

The description gives an explicit when-to-use ('analytical questions spanning entities or time windows') and names the alternative (atisbo_lookup mode=claim/node) for single-entity drill-downs. This is direct routing guidance, not just an implied context.

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

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

The annotations already indicate a destructive write operation (readOnlyHint=false, destructiveHint=true), and the description's 'update, patch or add' is consistent with that. However, the description adds no behavioral detail beyond the annotations—no mention of artefact mutation effects, idempotency keys, dirty_event_id side effects, or mode-specific consequences, which is significant for a destructive tool.

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 description is a single compact sentence with no filler, and the primary action is front-loaded. However, it is so terse that it fails to convey mode routing, so conciseness comes at the cost of practical guidance.

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?

This is a high-complexity tool with 26 parameters, six modes, nested objects, and no output schema, yet the description provides only a one-sentence overview. It gives no indication of which parameters apply to which mode, no mode-specific contracts, and no behavioral caveats, leaving the agent severely under-informed for correct invocation.

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 81%, so the schema already documents most parameters in detail, including mode, evidence, and patch_ops. The description itself only restates broad resource categories and provides no extra parameter-level meaning, so it neither helps nor hurts beyond the high-coverage 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 states a clear verb ('Capture') and resource ('Signals or knowledge') and also names additional artefact operations ('update, patch or add evidence to artefacts'). It broadly distinguishes this tool from analysis or support siblings, but it does not explain the mode-driven dispatch, so the scope remains somewhat broad.

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?

There is no guidance on when to use this tool versus siblings or how to choose between the six modes in the schema. The description does not mention alternatives, prerequisites, or mode selection criteria, leaving the agent to infer usage entirely from the parameter schema.

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

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

With annotations indicating destructiveHint=true, the description goes beyond by disclosing critical behavioral traits: Atisbo only READS a connected system, never writes; create returns an endpoint + signing secret shown EXACTLY ONCE and must be relayed immediately; config is stored encrypted and never readable again. These are exactly the kind of non-obvious behaviors an agent needs to know.

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 description is dense and front-loaded with the primary purpose (CONNECTS), and each sentence earns its place: modes summary, list-first rule, boundary expansion, read-only rule, and one-time secret warning. It loses one point because the heavy use of ALL-CAPS and the density of information could be slightly overwhelming, but nothing is redundant.

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 an 18-parameter tool with no output schema and nested objects, the description supplies the missing contexts: when to call list, catalog fallback behavior, read-only guarantee, one-time secret handling, pull-vs-instant distinction, and mode-to-parameter mapping. There is no output schema, so the return-value guidance ('catalog (ingestible sources; query filters)', 'create returns the endpoint') is appropriately brief but sufficient.

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?

Although schema coverage is 100%, the description adds crucial cross-parameter semantics: which parameters apply to which modes, that kwargs must pair with native_providers, that json_paths.raw_text is REQUIRED, and that sync_every applies only to PULL sources. It also explains consequences of parameter choices (e.g., email provisions an ingest address). This goes 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 names a specific verb (CONNECTS) and resource (Atisbo sources/signals), and immediately distinguishes itself from merely describing them. It enumerates concrete modes list, catalog, create, configure, pause, resume, sync_now, composio variants, making the tool's scope unmistakable and differentiating it from siblings like atisbo_analyze or atisbo_capture.

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?

The description gives explicit when-to-use instructions: 'Call list before any mutation', and warns against answering from an empty search, directing the agent to call catalog and read fallback. It also explains the CAPABILITIES boundary ('almost anything connects') and provides alternatives by mode. This is strong routing guidance.

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

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

Annotations already carry destructiveHint=true and readOnlyHint=false, lowering the bar. The description adds useful behavioral context beyond annotations: mutations are self-logged, writes need UUIDs, and declare_pm_exception signals a human-decision requirement. It does not disclose confirmation flows, return behavior, or which specific modes are destructive, but the annotation covers the destructive profile adequately.

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 description is compact and scannable, using CURATE/EXECUTE/DOCUMENT/GOVERN to compress a large surface area into a few sentences. It front-loads the tool's identity and every sentence carries some operational guidance. Minor jargon like 'facade' and the all-caps category labels are slightly cryptic, but the density is appropriate for the tool's breadth.

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?

Given 78 parameters, 28 modes, no output schema, and destructive behavior, the description is a minimum-viable orientation rather than a complete invocation guide. It supplies the critical guards (external-only log_decision, UUIDs) and broad mode families, but relies heavily on the schema for mode-specific semantics and does not mention return shapes or confirmation requirements.

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 91%, so the schema already documents most parameters and baseline is 3. The description itself adds little parameter-level meaning beyond the UUID requirement and a hint about declare_pm_exception. Mode-specific parameter relationships are left to the schema's per-parameter descriptions, which is acceptable given the high coverage.

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 a 'PM decision facade' and enumerates concrete action families with verbs and resources: curate evidence/deal-breakers, execute create/update/dispatch/delete Solutions, record Outcomes, and govern living docs/coverage/schedules/knowledge/strategy. It does not name one single operation, but for a 28-mode tool the mode enum supplies the granularity. The write-focused framing also helps separate it from read/analysis sibling tools.

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 delimits log_decision to external decisions ('mutations log themselves') and states a hard prerequisite for writes ('require UUIDs'). It also clarifies one mode's special meaning (declare_pm_exception on claims). It does not provide routing guidance for all 28 modes or name sibling alternatives explicitly, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: opening a snippet returns raw text plus signed attachment URLs, and other modes expose queues/outcomes/implementation context. It does not detail pagination or per-mode side-effect warnings, but for a read-only tool the important behaviors are stated.

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 sentences, no filler. The most decision-relevant behavior (snippet:// returns text and signed URLs) is front-loaded, and the second sentence orients the agent to the mode families without enumerating all 24 modes.

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 very complex tool (29 parameters, 24 modes, no output schema), the description is thin but the schema carries essentially all parameter semantics and the annotations carry the safety profile. The description adds the missing top-level map of what the modes do. A fully complete description would name a few high-usage modes and mention pagination, so this is not a 5.

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 100%, so the schema fully documents all 29 parameters, including enums and references. The description adds only a light interpretive gloss ('Other modes expose queues, outcomes and implementation context') and the snippet:// behavior. That is useful but does not materially clarify individual parameters; baseline 3 is appropriate.

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 a specific verb ('Find or open'), a concrete resource ('Atisbo entities'), and immediately gives a distinguishing behavior ('opening snippet:// returns its text and signed attachment URLs') plus a high-level inventory of alternative modes. This differentiates it from the sibling tools and from the other modes within the oversized enum.

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 states when to use the tool (finding/opening entities) and broadly separates read-style lookups from other modes ('Other modes expose queues, outcomes and implementation context'). It does not explicitly name sibling alternatives and exclude them, but the sibling names (atisbo_capture, atisbo_decide, etc.) make the predicate evident. The lack of an explicit 'use X for mutations' statement keeps it from a 5.

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

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

Annotations already supply readOnlyHint=false and destructiveHint=true. The description adds meaningful behavioral detail beyond that: mode=anchor sets the taxonomy category with one category per claim, refusing non-taxonomy maps, while mode=link_claims adds structural membership without changing the claim's category and refuses taxonomy maps. This helps the agent predict refusals and side effects without contradicting the annotations.

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 description is dense but every sentence earns its place: a one-line capability summary, a recommendation for 'apply', then the critical anchor-vs-link distinction. It is appropriately sized for a 17-mode facade, though it could be slightly more scannable with bullet separation.

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 tool with 45 parameters, 17 modes, and no output schema, the description gives solid orientation but leaves several modes under-explained (e.g., claim-snipe sync, edge creation, metric updates). The schema and the in-schema note about 'meta.guidance' help fill gaps, but an agent would still need to discover mode-specific behaviors through experimentation.

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?

With 64% schema coverage, the schema carries much of the parameter documentation, but the description adds high-value semantics for the central 'mode' parameter and related claim-placement fields. It clarifies what 'anchor' vs 'link_claims' actually do to a claim's category and explains the purpose of 'regroup'. The remaining parameters are reasonably documented in the schema, so the description compensates where it matters most.

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 opens with a clear scope ('Compact facade for map work') and enumerates concrete actions: create/apply maps, edit nodes and edges, anchor claims, bind metrics, manage claim-snipe maps, and regroup claims. It is broad because the tool is a multi-mode facade, but it still names specific resources and verbs, and the domain is clearly distinct from the sibling atisbo_ tools.

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?

The description gives explicit routing guidance: 'Prefer mode=apply for full MECE categorization' and contrasts the two claim-placement modes, stating they are 'not interchangeable' and specifying which map types each mode accepts or refuses. It does not discuss when to prefer this tool over sibling tools, but within the tool's many modes it provides actionable direction.

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

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

Annotations already mark the tool readOnly/non-destructive, so the bar is lower. The description adds behavioral context: it is an orientation/snapshot operation that should continue the existing workflow, never create a parallel backlog, and edits are routed through other tools (lookup then capture), implying orient itself is purely informational. No contradiction with annotations.

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?

Three sentences front-load the core modes before giving workflow routing, and each sentence carries information. It is dense and slightly jargon-heavy ('claim depth', 'parallel backlog'), but not bloated or redundant.

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 read-only, parameter-rich tool with full schema coverage, the description provides enough operational context, including mode-specific behaviors and how to continue with sibling tools. The absence of any mention of return format is a minor gap since no output schema exists, but the mode semantics and schema largely compensate.

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?

The schema covers 100% of parameters, including enum meanings and limit clamp behavior, so the baseline is 3. The description's mode list and 'depth=work for the full corpus' hint lightly supplement the schema but mostly restate it, so no higher score is earned.

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 distinct action, 'Workspace orientation,' and enumerates four modes with parenthetical meanings (snapshot overview, whats_new delta, strategy, integrations), so an agent can identify the resource and primary intent. It does not sharply contrast against siblings like atisbo_map or atisbo_lookup, but the sibling-routing sentences imply orient is the top-level orientation entry point.

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?

The description mentions continuing the user's existing workflow and never creating a parallel backlog, and it directs follow-on actions to atisbo_lookup, atisbo_analyze, and atisbo_capture. However, it does not explicitly state when orient should be preferred over siblings or list exclusions, so the guidance is more workflow context than crisp when-to-use/alternatives guidance.

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

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

Annotations already mark the tool read-only and non-destructive; the description adds meaningful behavioral detail: it returns a playbook, runs checks across integrations/ingestion/clustering, and discloses that share_report files only diagnostics plus the user's text, never customer names or document bodies. No contradiction with annotations.

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?

Three sentences with no waste: the first states purpose and examples, the second covers behavior and privacy, the third handles sibling routing. Information is front-loaded and every sentence adds value.

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 4-parameter diagnostic tool with a rich output schema and read-only annotations, the description covers scope, behavior, privacy, and alternatives. An agent has enough information to decide when to call it and what to expect.

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 100%, so the baseline applies. The main description adds little parameter-specific meaning beyond the schema, though it reinforces the privacy constraint on share_report. The schema already explains problem, area, share_report, and observed_error well.

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 opens with a specific verb and resource ('Diagnose Atisbo'), gives three concrete symptom examples, and lists the internal checks it performs. It explicitly routes backlog work to atisbo_lookup/atisbo_analyze, so an agent can distinguish this from sibling tools.

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 states what kinds of problems should be sent here ('I connected a source and nothing appeared', 'my data is missing') and explicitly identifies the alternative for backlog cases ('Use atisbo_lookup/atisbo_analyze for backlog'). This is clear when-to-use guidance with a named exclusion.

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