select_pci_proxies

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

Annotations declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe read operation. The description adds valuable context beyond annotations: it discloses the statistical assumptions (valid negative controls, bridge function existence), failure modes, and fallback strategies. It doesn't describe the exact output format, but the output schema exists and the detail parameter explains payload depths. The description adds substantial behavioral context without contradicting 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 compact and front-loaded with the core purpose. It uses labeled sections (Assumptions, Pre-conditions, Failure modes, Alternatives, Typical minimum N) that are scannable. It could be slightly more concise by trimming redundancy between assumptions and pre-conditions, but the structure is effective and every section 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?

For a tool with 11 parameters, full schema coverage, an output schema, and read-only annotations, the description covers the essential context: what it does, when to use it, what assumptions must hold, what to do if it fails, and sample size guidance. The only minor gap is not explicitly stating what the ranking output looks like, but the output schema and detail parameter descriptions cover that. This is complete enough for an agent to select and invoke 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%, so the schema already documents all 11 parameters thoroughly. The description doesn't add parameter-level detail beyond what the schema provides, but it does contextualize the 'candidates' parameter by explaining what makes a valid proxy (negative control relevance, exclusion from causal channel). The detail parameter's enum descriptions are already rich in the schema. Baseline 3 is appropriate given full schema 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 opens with a specific verb and resource: 'Score and rank candidate proxies for PCI.' It clearly distinguishes this tool from siblings like 'bidirectional_pci', 'fortified_pci', 'pci_mtp', and 'proximal' by focusing on proxy selection/ranking. The assumptions and pre-conditions further clarify its role in the PCI workflow.

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 explicitly states pre-conditions (treatment-inducing and outcome-inducing proxy variables), failure modes (weak/invalid proxies), and alternatives (sp.select_pci_proxies, sp.dml). It also provides a typical minimum N (500), giving the agent concrete guidance on when this tool is appropriate. This is exemplary usage guidance.

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