Show App Installation

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

The description adds meaningful behavioral context beyond the annotations: it explicitly states 'Read-only — it changes nothing in Procore' (consistent with readOnlyHint=true), and it discloses failure modes with common HTTP statuses (401, 403, 404) and their meanings. It also notes the return type as 'a single JSON object.' This is more informative than a minimal read-only hint, justifying a score above baseline.

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 well-structured and front-loaded: purpose, usage, prerequisite, output, safety, errors, and API reference. Every sentence contributes meaning, though 'Required parameters' repeats schema information and the Procore API path is contextually useful but not essential. It is appropriately sized for an API tool with 3 parameters.

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?

With no output schema, the description helps by specifying the return is 'a single JSON object.' It covers error scenarios and required parameters. However, it doesn't resolve the potential ambiguity in the schema regarding whether both company_id and project_id are truly required or whether either one suffices. Overall, the description is complete enough for a straightforward read-only GET 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that 'id must identify an existing parent record' and advising to resolve it with the list tool first, which is beyond the schema's definition of id as a 'unique identifier'. However, it simply lists all parameters as required without clarifying the 'either company_id or project_id' nuance that the schema descriptions mention, so it doesn't quite earn a 5.

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 'Get the details of a single app installation,' which uses a specific verb ('Get'), a specific resource ('app installation'), and explicitly states scope ('single'). This distinguishes it from list tools like list_app_installations_v1_0 and create_installation_request. The phrase 'need its full field set' further clarifies the purpose.

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 says 'Use this when you already know which app installation you want and need its full field set,' providing a clear usage context. It also instructs to resolve the id with 'the matching list tool first,' which guides the agent to the appropriate prerequisite tool. However, it does not explicitly name the alternative tool or state when not to use it, so it falls short of the top score.

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