publish_to_service

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

With no annotations provided, the description carries full burden and excels: it discloses the dual-mode behavior, the Import API vs Fabric items API routing, the 'nameConflict CreateOrOverwrite by default' default, the creation/update-in-place semantics, the AAD token requirement with Power BI scopes, and the security note that the token is never echoed. These are concrete, side-effect-relevant details.

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 dense sentences cover purpose, two artifact types, API routing, default conflict policy, ordering, auth, and security. No redundant words, and the information is front-loaded with the primary action and scoped in the first clause. Every sentence earns its place.

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 description is thorough for a complex dual-mode publishing tool, covering input types, API paths, ordering, defaults, and auth. It omits return values or error behavior, but given the lack of an output schema and the emphasis on the publish action, the absence is not a major gap. The description is nearly complete.

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 100% with already descriptive parameter text. The main description adds some context (notably the API routing and 'never echoed' for accessToken), but most parameters (workspaceId, datasetDisplayName, nameConflict) are already well-defined in the schema. The added value is marginal, so the 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 opens with 'Publish a built artifact to the Power BI Service', which names the specific action and target resource. It further differentiates between .pbix and PBIP folder paths, clarifying two distinct publishing modes and the APIs used (Import API vs Fabric items API), which sets it apart 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?

The description clearly states when the tool applies: for built artifacts, either a .pbix file or a PBIP folder from generate_pbip/scaffold. It describes the underlying flow and ordering (SemanticModel first, then Report) and references nameConflict default behavior. However, it does not explicitly call out alternative tools or exclusion cases, 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.