dataverse_get_organization_info

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description focuses on added context: each function is called independently, failures are collected in partial_errors, and only total failure yields an error response. It also discloses response shaping (@odata envelope removal) and performance-relevant solution summarization.

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 first sentence is a concise, front-loaded summary, and each following paragraph addresses a distinct, valuable concern: when to call, how to classify environments, solution handling, and partial-failure behavior. The length is justified by the tool's complexity, and no sentence is 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 description covers preconditions, environment-identity interpretation, output shaping, and partial-error semantics, which is complete for a tool that merges three Web API calls. An output schema is present, so the description does not need to enumerate every return field, but it still provides enough context to use the tool 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?

The schema itself documents dataverse_url, access_type, and include_solutions with clear descriptions. The tool description adds meaningful semantics for include_solutions—response-size impact, default behavior, and a preferred alternative tool. Access_type is not revisited in prose, but the schema already explains it thoroughly, so the gap is minor.

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 'Fingerprint a Dataverse environment: server version, organization identity, endpoints,' which names a specific verb, resource, and scope while distinguishing it from sibling lookup tools. It also differentiates the tool by naming the three merged Web API functions and the practical outputs it provides.

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?

Explicit usage guidance is provided: 'Call this before any risky operation to confirm which environment you are pointed at.' It also gives an explicit alternative for solutions browsing ('prefer dataverse_list_solutions') and warns against a common misclassification ('never test only for Sandbox').

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