run_sparql

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

With annotations already declaring readOnlyHint and openWorldHint, the description adds valuable behavioral context: invalid database/endpoint_name values fail immediately with a deterministic error and should not be retried, and results are returned as a CSV string with a header row. This goes beyond the annotations and helps set expectations.

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 core action, and every sentence carries critical information. It is longer than ideal due to the extensive enum lists, but those are necessary. The structure is logical, moving from basic usage to cross-database nuances to error and return behavior.

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 the tool's complexity (5 params, multiple endpoint options, cross-database scenarios, output schema), the description is thorough. It covers required parameters, valid values, endpoint priority, error behavior, and return format. The output schema exists, but the description additionally explains the CSV structure, making it fully self-contained.

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 significantly enriches parameter understanding: it lists all valid database values, explains that endpoint_url takes priority over database, and clarifies alias relationships (query vs. sparql_query). This is not merely restating schema; it provides essential operational semantics for correct usage.

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 clearly states the tool's function: 'Run a SPARQL query on an RDF database.' It uses a specific verb and resource, and the detailed guidance on single vs. cross-database queries distinguishes it from sibling search tools. However, it does not explicitly compare itself to alternatives like search_uniprot_entity, so it does not fully earn a 5.

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 provides explicit when-to-use instructions: ALWAYS pass database for single-database queries, and still pass a member database plus endpoint_name or endpoint_url for cross-database queries. It also clarifies priority and error behavior. Yet it does not mention alternatives (e.g., using search_* tools for standard queries), leaving the vs. alternatives aspect partially unaddressed.

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