List MCP Profiles

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description instead adds real behavioral context — the --db-path prerequisite and the fact that profile selection is immutable at runtime. Null-handling rules (null templateId, null tokenBudget means inherit through template then active PipelineProfile) are disclosed, though some of this drifts into return-shape territory rather than behavior.

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 purpose is front-loaded, but the body is a single sprawling sentence with stacked parentheticals and an ALL-CAPS 'AND' joining two unrelated payload descriptions (identity fields vs. render config). Splitting the return-field inventory from the usage note would make it far more scannable.

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?

There is no output schema, so the description carries the burden of explaining the return shape — and it does, field by field, including null semantics and the two toolSelection encodings. Combined with the stated prerequisite and the 'no runtime switch' constraint, an agent has everything needed to call and interpret this tool.

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 tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter guidance because none is needed.

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?

Opens with a specific verb+resource ('List the MCP profiles in the server's config DB') and enumerates the exact fields returned. No sibling tool in the list covers MCP profile configuration, so it is unambiguously distinguishable.

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?

States the prerequisite ('Requires the server to be started with --db-path') and explains what to do with the results ('Use the ids with aicb mcp --mcp-profile <id> to pin the profile at server start'). It also pre-empts a fruitless search by stating there is no runtime switch tool. It never frames when to call this versus another tool, but no viable alternative exists.

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